Struct dashu_float::Context

pub struct Context<RoundingMode: Round> { /* private fields */ }

The context containing runtime information for the floating point number and its operations.

The context currently consists of a precision limit and a rounding mode. All the operation associated with the context will be precise to the full precision (|error| < 1 ulp). The rounding result returned from the functions tells additional error information, see the rounding mode module for details.

Precision

The precision limit determine the number of significant digits in the float number.

For binary operations, the result will have the higher one between the precisions of two operands.

If the precision is set to 0, then the precision is unlimited during operations. Be cautious to use unlimited precision because it can leads to very huge significands. Unlimited precision is forbidden for some operations where the result is always inexact.

Rounding Mode

The rounding mode determines the rounding behavior of the float operations.

See the rounding mode module for built-in rounding modes. Users can implement custom rounding mode by implementing the Round trait, but this is discouraged since in the future we might restrict the rounding modes to be chosen from the the built-in modes.

For binary operations, the two oprands must have the same rounding mode.

Implementations

impl<R: Round> Context<R>

pub fn add<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B> ) -> Rounded<FBig<R, B>>

Add two floating point numbers under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("1.234")?;
let b = DBig::from_str("6.789")?;
assert_eq!(context.add(&a.repr(), &b.repr()), Inexact(DBig::from_str("8.0")?, NoOp));

pub fn sub<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B> ) -> Rounded<FBig<R, B>>

Subtract two floating point numbers under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("1.234")?;
let b = DBig::from_str("6.789")?;
assert_eq!(
    context.sub(&a.repr(), &b.repr()),
    Inexact(DBig::from_str("-5.6")?, SubOne)
);

impl<R: Round> Context<R>

pub fn convert_int<const B: Word>(&self, n: IBig) -> Rounded<FBig<R, B>>

Convert an IBig instance to a FBig instance with precision and rounding given by the context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
assert_eq!(context.convert_int::<10>((-12).into()), Exact(DBig::from_str("-12")?));
assert_eq!(
    context.convert_int::<10>(5678.into()),
    Inexact(DBig::from_str("5.7e3")?, AddOne)
);

impl<R: Round> Context<R>

pub fn div<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B> ) -> Rounded<FBig<R, B>>

Divide two floating point numbers under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("-1.234")?;
let b = DBig::from_str("6.789")?;
assert_eq!(context.div(&a.repr(), &b.repr()), Inexact(DBig::from_str("-0.18")?, NoOp));

Euclidean Division

To do euclidean division on the float numbers (get an integer quotient and remainder, equivalent to C99’s fmod and remquo), please use the methods provided by traits DivEuclid, RemEuclid and DivRemEuclid.

pub fn rem<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B> ) -> Rounded<FBig<R, B>>

Calculate the remainder of ⌈lhs / rhs⌋.

The remainder is calculated as r = lhs - ⌈lhs / rhs⌋ * rhs, the division rounds to the nearest and ties to away. So if n = (lhs / rhs).round(), then lhs == n * rhs + r (given enough precision).

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(3);
let a = DBig::from_str("6.789")?;
let b = DBig::from_str("-1.234")?;
assert_eq!(context.rem(&a.repr(), &b.repr()), Exact(DBig::from_str("-0.615")?));

pub fn inv<const B: Word>(&self, f: &Repr<B>) -> Rounded<FBig<R, B>>

Compute the multiplicative inverse of an FBig

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("-1.234")?;
assert_eq!(context.inv(&a.repr()), Inexact(DBig::from_str("-0.81")?, NoOp));

impl<R: Round> Context<R>

pub fn powi<const B: Word>( &self, base: &Repr<B>, exp: IBig ) -> Rounded<FBig<R, B>>

Raise the floating point number to an integer power under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str_native("-1.234")?;
assert_eq!(context.powi(&a.repr(), 10.into()), Inexact(DBig::from_str_native("8.2")?, AddOne));

Panics

Panics if the precision is unlimited and the exponent is negative. In this case, the exact result is likely to have infinite digits.

pub fn powf<const B: Word>( &self, base: &Repr<B>, exp: &Repr<B> ) -> Rounded<FBig<R, B>>

Raise the floating point number to an floating point power under this context.

Note that this method will not rely on FBig::powi even if the exp is actually an integer.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let x = DBig::from_str_native("1.23")?;
let y = DBig::from_str_native("-4.56")?;
assert_eq!(context.powf(&x.repr(), &y.repr()), Inexact(DBig::from_str_native("0.39")?, AddOne));

Panics

Panics if the precision is unlimited.

pub fn exp<const B: Word>(&self, x: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the exponential function (eˣ) on the floating point number under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str_native("-1.234")?;
assert_eq!(context.exp(&a.repr()), Inexact(DBig::from_str_native("0.29")?, NoOp));

pub fn exp_m1<const B: Word>(&self, x: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the exponential minus one function (eˣ-1) on the floating point number under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str_native("-0.1234")?;
assert_eq!(context.exp_m1(&a.repr()), Inexact(DBig::from_str_native("-0.12")?, SubOne));

impl<R: Round> Context<R>

pub fn ln<const B: Word>(&self, x: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the natural logarithm function (log(x)) on the float number under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("1.234")?;
assert_eq!(context.ln(&a.repr()), Inexact(DBig::from_str("0.21")?, NoOp));

pub fn ln_1p<const B: Word>(&self, x: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the natural logarithm function (log(x+1)) on the float number under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("0.1234")?;
assert_eq!(context.ln_1p(&a.repr()), Inexact(DBig::from_str("0.12")?, AddOne));

impl<R: Round> Context<R>

pub fn mul<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B> ) -> Rounded<FBig<R, B>>

Multiply two floating point numbers under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("-1.234")?;
let b = DBig::from_str("6.789")?;
assert_eq!(
    context.mul(&a.repr(), &b.repr()),
    Inexact(DBig::from_str("-8.4")?, SubOne)
);

pub fn sqr<const B: Word>(&self, f: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the square of the floating point number under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("-1.234")?;
assert_eq!(context.sqr(&a.repr()), Inexact(DBig::from_str("1.5")?, NoOp));

pub fn cubic<const B: Word>(&self, f: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the cubic of the floating point number under this context.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("-1.234")?;
assert_eq!(context.cubic(&a.repr()), Inexact(DBig::from_str("-1.9")?, SubOne));

impl<R: Round> Context<R>

pub const fn new(precision: usize) -> Self

Create a float operation context with the given precision limit.

pub const fn max(lhs: Self, rhs: Self) -> Self

Create a float operation context with the higher precision from the two context inputs.

Examples

use dashu_float::{Context, round::mode::Zero};

let ctxt1 = Context::<Zero>::new(2);
let ctxt2 = Context::<Zero>::new(5);
assert_eq!(Context::max(ctxt1, ctxt2).precision(), 5);

pub const fn precision(&self) -> usize

Get the precision limited from the context

impl<R: Round> Context<R>

pub fn sqrt<const B: Word>(&self, x: &Repr<B>) -> Rounded<FBig<R, B>>

Calculate the square root of the floating point number.

Examples

use dashu_base::Approximation::*;
use dashu_float::{Context, round::{mode::HalfAway, Rounding::*}};

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("1.23")?;
assert_eq!(context.sqrt(&a.repr()), Inexact(DBig::from_str("1.1")?, NoOp));

Panics

Panics if the precision is unlimited.

Trait Implementations

impl<RoundingMode: Clone + Round> Clone for Context<RoundingMode>

fn clone(&self) -> Context<RoundingMode>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<R: Round> Debug for Context<R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R: Round> Zeroize for Context<R>

fn zeroize(&mut self)

Zero out this object from memory using Rust intrinsics which ensure the zeroization operation is not “optimized away” by the compiler.

impl<RoundingMode: Copy + Round> Copy for Context<RoundingMode>