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.

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

// printing
assert_eq!(format!("{}", DBig::from_str_native("12.34")?), "12.34");
let x = DBig::from_str_native("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, rnd: HalfAway)"
    );
}

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

Implementations§

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

pub fn digits(&self) -> usize

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

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

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

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

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

pub fn ulp(&self) -> Self

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

pub fn ln(&self) -> Self

pub fn ln_1p(&self) -> Self

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

pub fn square(&self) -> Self

pub fn cubic(&self) -> Self

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

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

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

pub fn sqrt(&self) -> Self

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

pub fn trunc(&self) -> Self

pub fn split_at_point(self) -> (Self, Self)

pub fn fract(&self) -> Self

pub fn ceil(&self) -> Self

pub fn floor(&self) -> Self

pub fn round(&self) -> Self

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

pub const fn sign(&self) -> Sign

pub const fn signum(&self) -> Self

Trait Implementations§

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

type Output = FBig<R, B>

fn abs(self) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l FBig<R, B>

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l IBig

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l UBig

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l i128

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l i16

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l i32

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l i64

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

impl<'l, 'r, R: Round, const B: Word> Add<&'r FBig<R, B>> for &'l i8

type Output = FBig<R, B>

fn add(self, rhs: &FBig<R, B>) -> Self::Output

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

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