Struct dashu_float::FBig

source ·

pub struct FBig<RoundingMode: Round = Zero, const BASE: Word = 2> { /* private fields */ }

Expand description

An arbitrary precision floating point number with arbitrary base and rounding mode.

The float number consists of a Repr and a Context. The Repr instance determines the value of the number, and the Context contains runtime information (such as precision limit, rounding mode, etc.)

For how the number is represented, see Repr, for how the precision limit and rounding mode is applied, see Context.

The arithmetic operations on FBig follows the behavior of its associated context. If a different precision limit and/or rounding mode is required, or the rounding information has to be preserved, use the methods of the Context type.

§Generic Parameters

The const generic parameters will be abbreviated as BASE -> B, RoundingMode -> R. THe BASE must be in range [2, isize::MAX], and the RoundingMode can be chosen from the mode module.

With the default generic parameters, the floating number is of base 2 rounded towards zero. This is the most efficient format for operations. To represent a decimal number, the alias DBig is provided, which is base 10 rounded to the nearest.

§Parsing and printing

To create a FBig instance, there are four ways:

Use predifined constants (e.g. FBig::ZERO, FBig::ONE, FBig::NEG_INFINITY).
Use the literal macro fbig! or dbig! defined in the dashu-macro crate.
Construct from the significand and exponent using from_parts() or from_parts_const().
Parse from a string.

Conversion from and to str is limited to native radix (i.e. base). To print or parse with different radix, please use to_binary(), to_decimal() or with_base(), with_base_and_precision() to convert.

For printing, currently only the Display and Debug are supported. Other formatting traits will be supported in future.

use core::str::FromStr;

// parsing
let a = DBig::from_parts(123456789.into(), -5);
let b = DBig::from_str("1234.56789")?;
let c = DBig::from_str("1.23456789e3")?;
assert_eq!(a, b);
assert_eq!(b, c);

// printing
assert_eq!(format!("{}", DBig::from_str("12.34")?), "12.34");
let x = DBig::from_str("10.01")?
    .with_precision(0) // use unlimited precision
    .value();
if dashu_int::Word::BITS == 64 {
    // number of digits to display depends on the word size
    assert_eq!(
        format!("{:?}", x.powi(100.into())),
        "1105115697720767968..1441386704950100001 * 10 ^ -200 (prec: 0)"
    );
}

For detailed information of parsing, refer to the from_str_native() method.

§Restriction on binary operators

Binary operators on FBig instances are restricted to the same base and same rounding mode. This is designed to make sure that no hidden conversion is performed during the operators. However, for equality test and comparsion, two FBig instances can have different rounding modes (but not different bases), because rounding will never happends during comparison.

The infinities are converted as it is, and the subnormals are converted using its actual values.

§IEEE 754 behavior compliance

The representation of the floating point number doesn’t follows the IEEE 754 standard, as it’s not designed for arbitrary precision numbers. The key differences include:

FBig doesn’t support NaN values. In places where IEEE 754 operations generate NaNs, FBig will panic.
FBig doesn’t have subnormal values.
FBig doesn’t have negative zeros¹. There is only on zero value (FBig::ZERO).
Division by zero and logarithm on zero panic instead of returning infinities.
FBig operations will panic if the result overflows or underflows¹.
FBig does support infinities, but currently infinities are not allowed to be operated with, except for equality test and comparison¹.

¹ These behaviors are subject to changes in the future.

§Convert from/to `f32`/`f64`

Converting from f32/f64 to FBig is only defined for base 2 FBig (using TryFrom) to ensure the conversion is lossless. Since FBig doesn’t support NANs, converting f32::NAN or f64::NAN will return Err.

Converting to f32/f64 (using to_f32() and to_f64()) can be lossy, and the rounding direction is contained in the result of these two methods. To use the default IEEE 754 rounding mode (rounding to nearest), the Repr::to_f32 and Repr::to_f64 methods can be used for convenience.

§Convert from/to `UBig`/`IBig`

Converting from UBig and IBig is trivial and lossless through From. However, the reverse direction can be lossy.

The TryFrom trait and to_int() method are the two supported ways to convert from FBig to IBig. To convert to UBig, please first convert to IBig. When converting to IBig, TryFrom returns Ok only when the floating point number is not infinite and doesn’t have fractional part. To convert with rounding, use to_int() instead.

Struct dashu_float::FBig

§Generic Parameters

§Parsing and printing

§Restriction on binary operators

§IEEE 754 behavior compliance

§Convert from/to f32/f64

§Convert from/to UBig/IBig

Implementations§

impl<R: Round, const B: Word> FBig<R, B>

pub fn to_decimal(&self) -> Rounded<FBig<HalfAway, 10>>

§Examples

§Panics

pub fn to_binary(&self) -> Rounded<FBig<Zero, 2>>

§Examples

§Panics

pub fn with_precision(self, precision: usize) -> Rounded<Self>

§Examples

pub fn with_rounding<NewR: Round>(self) -> FBig<NewR, B>

§Examples

pub fn with_base<const NewB: Word>(self) -> Rounded<FBig<R, NewB>>

§Examples

§Panics

pub fn with_base_and_precision<const NewB: Word>( self, precision: usize ) -> Rounded<FBig<R, NewB>>

§Examples

§Panics

pub fn to_int(&self) -> Rounded<IBig>

§Warning

§Examples

§Panics

pub fn to_f32(&self) -> Rounded<f32>

§Examples

pub fn to_f64(&self) -> Rounded<f64>

§Examples

impl<R: Round, const B: Word> FBig<R, B>

pub fn powi(&self, exp: IBig) -> FBig<R, B>

§Examples

pub fn powf(&self, exp: &Self) -> Self

§Examples

pub fn exp(&self) -> FBig<R, B>

§Examples

pub fn exp_m1(&self) -> FBig<R, B>

§Examples

impl<R: Round, const B: Word> FBig<R, B>

pub fn from_repr(repr: Repr<B>, context: Context<R>) -> Self

§Examples

§Panics

pub const fn from_repr_const(repr: Repr<B>) -> Self

§Examples

pub const ZERO: Self = _

pub const ONE: Self = _

pub const NEG_ONE: Self = _

pub const INFINITY: Self = _

pub const NEG_INFINITY: Self = _

pub const fn precision(&self) -> usize

§Examples

pub fn digits(&self) -> usize

§Examples

pub const fn context(&self) -> Context<R>

pub const fn repr(&self) -> &Repr<B>

pub fn into_repr(self) -> Repr<B>

§Examples

pub fn from_parts(significand: IBig, exponent: isize) -> Self

§Examples

pub const fn from_parts_const( sign: Sign, significand: DoubleWord, exponent: isize, min_precision: Option<usize> ) -> Self

§Examples

pub fn ulp(&self) -> Self

§Examples

§Panics

impl<R: Round, const B: Word> FBig<R, B>

pub fn ln(&self) -> Self

§Examples

pub fn ln_1p(&self) -> Self

§Examples

impl<R: Round, const B: Word> FBig<R, B>

pub fn sqr(&self) -> Self

§Examples

pub fn cubic(&self) -> Self

§Examples

impl<R: Round, const B: Word> FBig<R, B>

pub fn from_str_native(src: &str) -> Result<Self, ParseError>

§Convert from/to `f32`/`f64`

§Convert from/to `UBig`/`IBig`