Struct 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 pi<const B: Word>(&self) -> Rounded<FBig<R, B>>

Calculate π using the Chudnovsky algorithm with binary splitting.

The Chudnovsky algorithm is one of the most efficient methods for high-precision π calculation, providing ~14.18 decimal digits per term.

Methodology

We use Binary Splitting to evaluate the series. This technique transforms the linear-time summation into a recursive tree evaluation. By combining terms into large products, it allows the library to leverage fast multiplication algorithms (like Toom-3 or FFT) as the numbers grow, leading to significant performance gains over simple iterative summation.

// TODO: consider adding a static cache for π at common precisions.

impl<R: Round> Context<R>

pub fn sin<const B: Word>(&self, x: &Repr<B>) -> FpResult<B>

Calculate the sine of the floating point representation.

pub fn cos<const B: Word>(&self, x: &Repr<B>) -> FpResult<B>

Calculate the cosine of the floating point representation.

pub fn sin_cos<const B: Word>(&self, x: &Repr<B>) -> (FpResult<B>, FpResult<B>)

Calculate both the sine and cosine of the floating point representation.

This is more efficient than calling sin and cos separately.

pub fn tan<const B: Word>(&self, x: &Repr<B>) -> FpResult<B>

Calculate the tangent of the floating point representation.

Note

Near odd multiples of π/2, the result returns Infinite.

pub fn asin<const B: Word>(&self, x: &Repr<B>) -> FpResult<B>

Calculate the arcsine of the floating point representation.

Methodology

Uses the identity: asin(x) = atan(x / sqrt(1 - x^2)) Returns NaN if |x| > 1.

pub fn acos<const B: Word>(&self, x: &Repr<B>) -> FpResult<B>

Calculate the arccosine of the floating point representation.

Methodology

Uses the identity: acos(x) = pi/2 - asin(x). Higher precision is used internally to avoid catastrophic cancellation near x ≈ 1.

pub fn atan<const B: Word>(&self, x: &Repr<B>) -> FpResult<B>

Calculate the arctangent of the floating point representation.

pub fn atan2<const B: Word>(&self, y: &Repr<B>, x: &Repr<B>) -> FpResult<B>

Calculate the arctangent of y / x.

Handles signed infinities according to IEEE 754 standards. Returns NaN if both arguments are zero.

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.

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

Calculate the cubic 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("8")?;
assert_eq!(context.cbrt(&a.repr()), Exact(DBig::from_str("2")?));

Panics

Panics if the precision is unlimited.

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

Calculate the nth 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("27")?;
assert_eq!(context.nth_root(3, &a.repr()), Exact(DBig::from_str("3")?));

Panics

Panics if n is zero, if the precision is unlimited, or if n is even and x is negative.

Trait Implementations

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

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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.