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 crate::round::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, with the quotient rounded to an integer by this context’s rounding mode.

The remainder is r = lhs - n * rhs, where n is the quotient rounded under the mode (e.g. Zero truncates n, so r keeps the dividend’s sign; the half modes bound |r| by |rhs|/2). The remainder value is exact; the returned flag only reports whether it had to be rounded down to the context precision.

Examples

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

let a = DBig::from_str("6.789")?;
let b = DBig::from_str("-1.234")?;

// the quotient −5.503… rounds to −6 half away from zero
let context = Context::<HalfAway>::new(3);
assert_eq!(context.rem(&a.repr(), &b.repr()), Ok(Exact(DBig::from_str("-0.615")?)));

// truncating the quotient instead: 6.789 = (−5)·(−1.234) + 0.619
let context = Context::<Zero>::new(3);
assert_eq!(
    context.rem(&a.repr(), &b.repr()),
    Ok(Exact(FBig::<Zero, 10>::from_str("0.619")?))
);

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.

Both Overflow and Underflow saturate to the directed endpoint — outward/nearest modes reach ±∞ (overflow) or the smallest representable (underflow); inward modes (toward-zero, opposite-infinity) reach the largest finite or signed zero — so the saturation honors the rounding mode (e.g. Up(pow(x, y)) agrees with Up(exp(y·ln x))). Overflow panics at unlimited precision (the largest finite is undefined). All other error variants panic (infinite input, out-of-domain, indeterminate).

impl<R: ErrorBounds> 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, correctly rounded via a Ziv retry loop.

base^n is computed by left-to-right binary exponentiation (repeated squaring); a negative exponent computes (1/base)^|n|, so the sign-dependent overflow/underflow falls out naturally. Each squaring compounds the relative error (it roughly doubles per step), so after n.bit_len() squarings the error is bounded by about 2^nlen · ulp — the Ziv radius reflects that, and the loop retries with more guard digits until the working-precision interval unambiguously determines the target rounding.

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 (the exact 1/base is not finite in general).

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.

A non-integer exponent is correctly rounded via a Ziv loop. An integer-valued exponent delegates to powi (binary exponentiation), which also accepts a negative base — its sign is fixed by the exponent’s parity — so pow(-x, n) is in domain here for integer n. Both paths are correctly rounded.

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: ErrorBounds> 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 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)));

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

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

Correctly rounded to the context’s precision under any rounding mode; for an exact power of two the result is the exact integer log2(x).

Domain

log2(±0) = −∞ and a negative (non-zero) input is out of domain; an infinite input is an error (a finite context cannot produce the infinite log2(+∞) = +∞ exactly).

Examples

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

let context = Context::<HalfAway>::new(4);
let a = DBig::from_str("10")?;
assert_eq!(context.log2(&a.repr(), None), Ok(Inexact(DBig::from_str("3.322")?, AddOne)));

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

Calculate the base-10 logarithm (log10(x)) on the float number under this context.

Correctly rounded to the context’s precision under any rounding mode; for an exact power of ten the result is the exact integer log10(x).

Domain

log10(±0) = −∞ and a negative (non-zero) input is out of domain; an infinite input is an error (a finite context cannot produce the infinite log10(+∞) = +∞ exactly).

Examples

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

let context = Context::<HalfAway>::new(4);
let a = DBig::from_str("100")?;
assert_eq!(context.log10(&a.repr(), None), Ok(Exact(DBig::from_str("2")?)));

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

Hyperbolic sine of x·π, i.e. sinh(x·π).

Methodology

The argument ball t = π·x (π from the shared constant cache, both roundings tracked by the ball arithmetic) feeds the all-positive sinh Maclaurin series for |t| ≤ 1 — where the exponential form’s exp(t) − exp(−t) would catastrophically cancel — and the ball exp composition beyond (|exp(t)| / |exp(−t)| ≥ e² there, a benign difference). Unlike the circular ×π functions there are no rational special points (π·x is transcendental for every nonzero rational x), so the zero case is the only exact one.

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

Hyperbolic cosine of x·π, i.e. cosh(x·π).

Methodology

The same t = π·x ball as sinh_pi: the all-positive cosh series for |t| ≤ 1, the (exp(t) + exp(−t))/2 sum beyond (same-sign terms, no cancellation).

pub fn sinh_cosh_pi<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).

This is more efficient than calling sinh_pi and cosh_pi separately, since the two share the argument ball and the exponential composition.

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: ErrorBounds> 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 value grows without bound; dashu’s wide exponent range holds it as a large finite number rather than saturating to ±∞.

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

Calculate the sine of 2π·x/u — the ×u family with u = 2 (i.e. sin(x·π)).

See sin_unit for the semantics; this is a thin wrapper.

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

Calculate the sine of 2π·x/u (the angle x is measured in units of the full turn divided by u; e.g. u = 360 gives degrees).

Methodology

The ×u variant has rational special points: the argument reduces exactly mod u in integer arithmetic, so arguments where 12x/u is an integer resolve to exact values (0, ±1, ±1/2) and — unlike sin — the accuracy does not degrade with the magnitude of x. The exact cases are resolved before the Ziv loop, whose containment test cannot certify exact values under directed rounding; the general path evaluates the sine/cosine series on the exact rational remainder r = |x| − k·u/4 ∈ [−u/8, u/8] scaled by 2π/u.

Returns Err(OutOfDomain) if u = 0.

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

Calculate the cosine of 2π·x/u — the ×u family with u = 2 (i.e. cos(x·π)).

See cos_unit for the semantics; this is a thin wrapper.

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

Calculate the cosine of 2π·x/u (see sin_unit for the ×u semantics).

Methodology

Exact whenever 12x/u is an integer (integers map to ±1, odd multiples of u/4 to +0, the cosine sixths to ±1/2); the general path is sin_unit’s with the cos quadrant mapping. cos is even, so the result never depends on the sign of x.

Returns Err(OutOfDomain) if u = 0.

pub fn sin_cos_pi<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 2π·x/u — the ×u family with u = 2.

See sin_cos_unit; this is a thin wrapper.

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

Calculate both the sine and cosine of 2π·x/u.

This is more efficient than calling sin_unit and cos_unit separately — except at the sixth-type exact points, where exactly one of the two results is exact (±1/2 vs ±√3/2) and the other is evaluated on its own.

Returns Err(OutOfDomain) in both slots if u = 0.

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

Calculate the tangent of 2π·x/u — the ×u family with u = 2 (i.e. tan(x·π)).

See tan_unit for the semantics; this is a thin wrapper.

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

Calculate the tangent of 2π·x/u (see sin_unit for the ×u semantics).

Methodology

Every quarter-type argument (u a multiple of u/4) is exact: integers map to ±0, quarter-integers to ±1. The odd multiples of u/4 are the poles: tan approaches +∞ from one side and −∞ from the other, so the sign of an infinity is unknown there — like 0/0, the case is reported as FpError::Indeterminate instead of guessing a sign. Otherwise sin_unit/cos_unit share one series evaluation; near a pole the wide exponent range holds a large finite value, as for tan.

Returns Err(OutOfDomain) if u = 0.

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

Calculate asin(x)·u/(2π) — the arc sine expressed in units of the full turn divided by u (e.g. u = 360 gives degrees). The inverse of sin_unit.

Methodology

The exact-value rows resolve outside the Ziv loop (directed rounding cannot certify them there): asin(±0) = ±0, asin(±1) = ±u/4, and asin(±1/2) = ±u/12. The general path scales the Ball composition of the radian asin by u/(2π).

u = 0 is the limit u·asin(x)/(2π) → ±0 (the signed zero, matching the function’s oddness, in-domain inputs only); returns Err(OutOfDomain) if |x| > 1 — the domain error outranks the u = 0 limit (asin_unit(2, 0) is an error, not +0).

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

Calculate acos(x)·u/(2π) — the arc cosine in units of the full turn divided by u. The inverse of cos_unit.

Methodology

Uses the identity acos(x) = π/2 − asin(x) scaled by u/(2π), i.e. u/4 − asin_unit(x). Exact rows (outside the Ziv loop): acos(+1) = 0, acos(−1) = u/2, acos(±0) = u/4, acos(±1/2) = u/6 / u/3.

u = 0 is the limit u·acos(x)/(2π) → +0 (acos ≥ 0, in-domain inputs only); returns Err(OutOfDomain) if |x| > 1 — the domain error outranks the u = 0 limit.

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

Calculate atan(x)·u/(2π) — the arc tangent in units of the full turn divided by u. The inverse of tan_unit.

Methodology

Exact rows (outside the Ziv loop): atan(±0) = ±0, atan(±1) = ±u/8, atan(±inf) = ±u/4. The general path scales the radian atan composition by u/(2π).

u = 0 is the limit u·atan(x)/(2π) → ±0 (the signed zero, matching the oddness).

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

Calculate atan2(y, x)·u/(2π) — the four-quadrant arc tangent in units of the full turn divided by u. The inverse of tan_unit with quadrant disambiguation.

Methodology

The axis/infinity special values follow the same C99 signed-zero model as atan2, with the π-multiples mapped to their u-fractions (π/4 → u/8, π/2 → u/4, 3π/4 → 3u/8, π → u/2). The general path scales the radian atan2 by u/(2π).

u = 0 is the limit u·atan2(y, x)/(2π) → ±0 (the sign of the angle). Returns Err(OutOfDomain) if both arguments are zero.

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) by binary splitting on 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 is the optimal algorithm for e (O(M(n) log n), faster than π) and avoids the argument-reduction and √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 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: ErrorBounds> 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 (correctly rounded).

The integer square root of the exponent-aligned significand (which carries ~2·p digits) is computed exactly, and its rounding to p digits is decided in a single step from the round digit and the sqrtrem remainder (the sticky bit) — the same principle as MPFR. When the root has p + 1 digits it is rounded directly to p digits, avoiding the double rounding that a rem-vs-root + re-round path incurs. For a power-of-two base this fast path is already correctly rounded; for other bases the result is additionally certified by a Ziv loop (the base-B digit alignment of an integer square root is only clean when the base is a power of two).

Panics

Panics if the precision is unlimited.

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 result is correctly rounded via a Ziv retry loop (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: Round> Archive for Context<RoundingMode>

where usize: Archive, PhantomData<RoundingMode>: Archive,

type Archived = ArchivedContext<RoundingMode>

The archived representation of this type.

type Resolver = ContextResolver<RoundingMode>

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

unsafe fn resolve( &self, pos: usize, resolver: Self::Resolver, out: *mut Self::Archived, )

Creates the archived version of this value at the given position and writes it to the given output.

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

fn clone(&self) -> Self

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<__D: Fallible + ?Sized, RoundingMode: Round> Deserialize<Context<RoundingMode>, __D> for Archived<Context<RoundingMode>>

where usize: Archive, Archived<usize>: Deserialize<usize, __D>, PhantomData<RoundingMode>: Archive, Archived<PhantomData<RoundingMode>>: Deserialize<PhantomData<RoundingMode>, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<Context<RoundingMode>, __D::Error>

Deserializes using the given deserializer

impl<__S: Fallible + ?Sized, RoundingMode: Round> Serialize<__S> for Context<RoundingMode>

where usize: Serialize<__S>, PhantomData<RoundingMode>: Serialize<__S>,

fn serialize(&self, serializer: &mut __S) -> Result<Self::Resolver, __S::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

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.