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 addsub_vv<const B: Word>( &self, lhs: Repr<B>, rhs: Repr<B>, rhs_sign: Sign, ) -> Rounded<Repr<B>>

Add or subtract two finite floats, consuming both operands.

Computes lhs + rhs_sign · rhs: Sign::Positive adds, Sign::Negative subtracts. This is the low-level ownership-aware kernel shared by the +/- operators and add/sub; unlike those it returns the raw rounded Repr (no FBig wrapping, no Result) and reuses the owned significand buffer of lhs. The _vr/_rv/_rr siblings cover the other ownership combinations and share this contract.

Panics

Panics if either operand is infinite (matching the other repr_* kernels).

Examples

use dashu_base::Sign::*;
use dashu_float::{Context, Repr, round::mode::HalfEven};
use dashu_int::IBig;

let ctx = Context::<HalfEven>::new(4);
let a = Repr::<10>::new(IBig::from(1234), -3); // 1.234
let b = Repr::<10>::new(IBig::from(5678), -4); // 0.5678
// 1.234 + 0.5678 = 1.8018, rounds (HalfEven, prec 4) to 1.802
assert_eq!(ctx.addsub_vv(a.clone(), b.clone(), Positive).value(),
           Repr::<10>::new(IBig::from(1802), -3));
// 1.234 - 0.5678 = 0.6662 (exact at prec 4)
assert_eq!(ctx.addsub_vv(a, b, Negative).value(),
           Repr::<10>::new(IBig::from(6662), -4));

pub fn addsub_vr<const B: Word>( &self, lhs: Repr<B>, rhs: &Repr<B>, rhs_sign: Sign, ) -> Rounded<Repr<B>>

Like addsub_vv but with the right operand borrowed (the left operand is consumed). See addsub_vv for the full contract.

pub fn addsub_rv<const B: Word>( &self, lhs: &Repr<B>, rhs: Repr<B>, rhs_sign: Sign, ) -> Rounded<Repr<B>>

Like addsub_vv but with the left operand borrowed and the right operand consumed. See addsub_vv for the full contract.

pub fn addsub_rr<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B>, rhs_sign: Sign, ) -> Rounded<Repr<B>>

Like addsub_vv but with both operands borrowed (the larger-exponent operand is cloned once for in-place alignment). See addsub_vv for the full contract.

pub fn add<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B>, ) -> FpResult<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()), Ok(Inexact(DBig::from_str("8.0")?, NoOp)));

pub fn sub<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B>, ) -> FpResult<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()),
    Ok(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>, ) -> FpResult<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()), Ok(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>, ) -> FpResult<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()), Ok(Exact(DBig::from_str("-0.615")?)));

pub fn inv<const B: Word>(&self, f: &Repr<B>) -> FpResult<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()), Ok(Inexact(DBig::from_str("-0.81")?, NoOp)));

impl<R: Round> Context<R>

pub fn unwrap_fp<const B: Word>( &self, result: FpResult<FBig<R, B>>, ) -> FBig<R, B>

Unwrap an FpResult, returning the value directly.

Converts Overflow to a signed infinity and Underflow to a signed zero. All other error variants panic (infinite input, out-of-domain, indeterminate).

impl<R: Round> Context<R>

pub fn powi<const B: Word>( &self, base: &Repr<B>, exp: IBig, ) -> FpResult<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("-1.234")?;
assert_eq!(context.powi(&a.repr(), 10.into()), Ok(Inexact(DBig::from_str("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>, cache: Option<&mut ConstCache>, ) -> FpResult<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("1.23")?;
let y = DBig::from_str("-4.56")?;
assert_eq!(context.powf(&x.repr(), &y.repr(), None), Ok(Inexact(DBig::from_str("0.39")?, AddOne)));

Panics

Panics if the precision is unlimited.

pub fn exp<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<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("-1.234")?;
assert_eq!(context.exp(&a.repr(), None), Ok(Inexact(DBig::from_str("0.29")?, NoOp)));

pub fn exp_m1<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<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("-0.1234")?;
assert_eq!(context.exp_m1(&a.repr(), None), Ok(Inexact(DBig::from_str("-0.12")?, SubOne)));

impl<R: Round> Context<R>

pub fn ln<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<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(), None), Ok(Inexact(DBig::from_str("0.21")?, NoOp)));

pub fn log2<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the base-2 logarithm function (log2(x)) on the float number under this context.

This is evaluated as ln(x) / ln(2) at an elevated working precision and rounded once, so it is correctly rounded to this context’s precision (unlike log2_bounds, which only gives an f32-precision magnitude estimate).

Examples

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

let context = Context::<HalfEven>::new(8);
let a = DBig::from_str("10")?;
// log2(10) ≈ 3.3219281
assert_eq!(context.log2(&a.repr(), None).unwrap().value(), DBig::from_str("3.3219281")?);

pub fn ln_1p<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<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(), None), Ok(Inexact(DBig::from_str("0.12")?, AddOne)));

impl<R: Round> Context<R>

pub fn sinh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Hyperbolic sine.

pub fn cosh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Hyperbolic cosine.

pub fn sinh_cosh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> (FpResult<FBig<R, B>>, FpResult<FBig<R, B>>)

Simultaneously compute sinh(x) and cosh(x) (context layer). Returns (sinh_result, cosh_result) where each is a FpResult.

This is more efficient than calling sinh and cosh separately, since the two share the exp_m1(±x) sub-computations.

pub fn tanh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Hyperbolic tangent.

pub fn asinh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Inverse hyperbolic sine.

pub fn acosh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Inverse hyperbolic cosine. Domain: x ≥ 1.

pub fn atanh<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Inverse hyperbolic tangent. Domain: -1 < x < 1 (x = ±1 → ±∞, |x| > 1 is an error).

impl<R: Round> Context<R>

pub fn sin<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the sine of the floating point representation.

pub fn cos<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the cosine of the floating point representation.

pub fn sin_cos<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> (FpResult<FBig<R, B>>, FpResult<FBig<R, 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>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the tangent of the floating point representation.

Note

Near odd multiples of π/2, the result is an infinity (returned as a value, not an error).

pub fn asin<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the arcsine of the floating point representation.

Methodology

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

pub fn acos<const B: Word>( &self, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, 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>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the arctangent of the floating point representation.

pub fn atan2<const B: Word>( &self, y: &Repr<B>, x: &Repr<B>, cache: Option<&mut ConstCache>, ) -> FpResult<FBig<R, B>>

Calculate the arctangent of y / x.

Handles signed infinities according to IEEE 754 standards. Returns Err(OutOfDomain) if both arguments are zero.

impl<R: Round> Context<R>

pub fn pi<const B: Word>( &self, cache: Option<&mut ConstCache>, ) -> 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.

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

Calculate e (Euler’s number) using binary splitting on the series e = Σ 1/k!.

Unlike pi, this takes no constant cache: e depends on no other cached constant and is itself reused by no operation, so there is no state worth sharing across calls. The factorial series with binary splitting is the optimal algorithm here — asymptotically O(M(n) log n) under FFT multiplication (faster than π’s O(M(n) log²n)), and it avoids both the ln-based argument reduction and the √p-fold powering that exp(1) would pay for.

Panics

Panics if the context precision is 0.

impl<R: Round> Context<R>

pub fn mul<const B: Word>( &self, lhs: &Repr<B>, rhs: &Repr<B>, ) -> FpResult<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()),
    Ok(Inexact(DBig::from_str("-8.4")?, SubOne))
);

pub fn sqr<const B: Word>(&self, f: &Repr<B>) -> FpResult<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()), Ok(Inexact(DBig::from_str("1.5")?, NoOp)));

pub fn cubic<const B: Word>(&self, f: &Repr<B>) -> FpResult<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()), Ok(Inexact(DBig::from_str("-1.9")?, SubOne)));

pub fn fma<const B: Word>( &self, a: &Repr<B>, b: &Repr<B>, c: &Repr<B>, sign: Sign, ) -> FpResult<FBig<R, B>>

Fused multiply–add under this context: c + sign·(a·b), rounded once.

The product a·b is formed exactly, then added to c with a single rounding (reusing the aligned-then-round path of add, so the severe-cancellation and sticky-tail handling is identical — including the single guard digit an effective subtraction may leave in the result). sign scales the product: Sign::Positive → a·b + c, Sign::Negative → c − a·b.

Returns FpError::InfiniteInput if any operand is infinite (matching add/mul; dashu rejects infinite operands outright, so the IEEE-754 inf·0 / inf−inf indeterminate forms do not arise). Overflow/Underflow propagate from the product’s exponent.

Examples

let context = Context::<HalfAway>::new(2);
let a = DBig::from_str("1.5")?;
let b = DBig::from_str("2.0")?;
let c = DBig::from_str("0.1")?;
assert_eq!(
    context.fma(&a.repr(), &b.repr(), &c.repr(), Sign::Positive),
    Ok(Exact(DBig::from_str("3.1")?))
);

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>) -> FpResult<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()), Ok(Inexact(DBig::from_str("1.1")?, NoOp)));

Panics

Panics if the precision is unlimited.

pub fn cbrt<const B: Word>(&self, x: &Repr<B>) -> FpResult<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()), Ok(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>, ) -> FpResult<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()), Ok(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.

impl<R: Round> Context<R>

pub fn hypot<const B: Word>( &self, a: &Repr<B>, b: &Repr<B>, ) -> FpResult<FBig<R, B>>

Compute sqrt(a² + b²) without spurious overflow/underflow.

This is the overflow-safe scaled sum-of-squares: the larger-magnitude operand is never squared. Writing m = max(|a|, |b|) and r = min(|a|,|b|) / m (so |r| ≤ 1), the result is m · sqrt(1 + r²), where 1 + r² ∈ [1, 2] cannot overflow. The final m · sqrt(1 + r²) overflows only when the true result genuinely exceeds the exponent range (reported as FpError::Overflow). hypot(±inf, ·) = +inf, hypot(0, 0) = +0.

This is a field-arithmetic-class op (no constant cache), like sqrt/atan2.

Panics

Panics if the precision is unlimited.

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.