Struct astro_float::BigFloat

pub struct BigFloat { /* private fields */ }

A floating point number of arbitrary precision.

Implementations

impl BigFloat

pub fn new(p: usize) -> Self

Returns a new number with value of 0 and precision of p bits. Precision is rounded upwards to the word size.

pub fn from_f64(f: f64, p: usize) -> Self

Constructs a number with precision p from f64 value. Precision is rounded upwards to the word size.

pub fn from_f32(f: f32, p: usize) -> Self

Constructs a number with precision p from f32 value. Precision is rounded upwards to the word size.

pub fn is_inf_pos(&self) -> bool

Returns true if self is positive infinity.

pub fn is_inf_neg(&self) -> bool

Returns true if self is negative infinity.

pub fn is_inf(&self) -> bool

Returns true if self is infinite.

pub fn is_nan(&self) -> bool

Return true if self is not a number.

pub fn get_err(&self) -> Option<Error>

Returns the associated with NaN error, if any.

pub fn add(&self, d2: &Self, p: usize, rm: RoundingMode) -> Self

Adds d2 to self and returns the result of the operation with precision p rounded according to rm. Precision is rounded upwards to the word size.

pub fn add_full_prec(&self, d2: &Self) -> Self

Adds d2 to self and returns the result of the operation. The resulting precision is equal to the full precision of the result. This operation can be used to emulate integer addition.

pub fn sub(&self, d2: &Self, p: usize, rm: RoundingMode) -> Self

Subtracts d2 from self and returns the result of the operation with precision p rounded according to rm. Precision is rounded upwards to the word size.

pub fn sub_full_prec(&self, d2: &Self) -> Self

Subtracts d2 from self and returns the result of the operation. The resulting precision is equal to the full precision of the result. This operation can be used to emulate integer subtraction.

pub fn mul(&self, d2: &Self, p: usize, rm: RoundingMode) -> Self

Multiplies d2 by self and returns the result of the operation with precision p rounded according to rm. Precision is rounded upwards to the word size.

pub fn mul_full_prec(&self, d2: &Self) -> Self

Multiplies d2 by self and returns the result of the operation. The resulting precision is equal to the full precision of the result. This operation can be used to emulate integer multiplication.

pub fn div(&self, d2: &Self, p: usize, rm: RoundingMode) -> Self

Divides self by d2 and returns the result of the operation with precision p rounded according to rm. Precision is rounded upwards to the word size.

pub fn rem(&self, d2: &Self) -> Self

Returns the remainder of division of |self| by |d2|. The sign of the result is set to the sign of self.

pub fn cmp(&self, d2: &BigFloat) -> Option<i128>

Compares self to d2. Returns positive if self > d2, negative if self < d2, zero if self == d2, None if self or d2 is NaN.

pub fn abs_cmp(&self, d2: &Self) -> Option<i128>

Compares the absolute value of self to the absolute value of d2. Returns positive if |self| is greater than |d2|, negative if |self| is smaller than |d2|, 0 if |self| equals to |d2|, None if self or d2 is NaN.

pub fn inv_sign(&mut self)

Reverses the sign of self.

pub fn pow(&self, n: &Self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Compute the power of self to the n with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn powi(&self, n: usize, p: usize, rm: RoundingMode) -> Self

Compute the power of self to the integer n with precision p. The result is rounded using the rounding mode rm. Precision is rounded upwards to the word size.

pub fn log(&self, n: &Self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the logarithm base n of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn is_positive(&self) -> bool

Returns true if self is positive. The function returns false if self is NaN.

pub fn is_negative(&self) -> bool

Returns true if self is negative. The function returns false if self is NaN.

pub fn is_subnormal(&self) -> bool

Returns true if self is subnormal. A number is subnormal if the most significant bit of the mantissa is not equal to 1.

pub fn is_zero(&self) -> bool

Returns true if self is zero.

pub fn clamp(&self, min: &Self, max: &Self) -> Self

Restricts the value of self to an interval determined by the values of min and max. The function returns max if self is greater than max, min if self is less than min, and self otherwise. If either argument is NaN or min is greater than max, the function returns NaN.

pub fn max(&self, d1: &Self) -> Self

Returns the value of d1 if d1 is greater than self, or the value of self otherwise. If either argument is NaN, the function returns NaN.

pub fn min(&self, d1: &Self) -> Self

Returns value of d1 if d1 is less than self, or the value of self otherwise. If either argument is NaN, the function returns NaN.

pub fn signum(&self) -> Self

Returns a BigFloat with the value -1 if self is negative, 1 if self is positive, zero otherwise. The function returns NaN If self is NaN.

pub fn parse(s: &str, rdx: Radix, p: usize, rm: RoundingMode) -> Self

Parses a number from the string s. The function expects s to be a number in scientific format in base 10, or +-Inf, or NaN.

Examples

use astro_float::BigFloat;
use astro_float::Radix;
use astro_float::RoundingMode;

let n = BigFloat::parse("0.0", Radix::Bin, 64, RoundingMode::ToEven);
assert!(n.is_zero());

let n = BigFloat::parse("1.124e-24", Radix::Dec, 128, RoundingMode::ToEven);
assert!(n.sub(&BigFloat::from_f64(1.124e-24, 128), 128, RoundingMode::ToEven).get_exponent() <= Some(-52 - 24));

let n = BigFloat::parse("-Inf", Radix::Hex, 1, RoundingMode::None);
assert!(n.is_inf_neg());

let n = BigFloat::parse("NaN", Radix::Oct, 2, RoundingMode::None);
assert!(n.is_nan());

pub fn random_normal(p: usize, exp_from: Exponent, exp_to: Exponent) -> Self

Returns a random normalized (not subnormal) BigFloat number with exponent in the range from exp_from to exp_to inclusive. The sign can be positive and negative. Zero is excluded. Precision is rounded upwards to the word size. Function does not follow any specific distribution law. The intended use of this function is for testing.

pub fn classify(&self) -> FpCategory

Returns category of self.

pub fn atan(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the arctangent of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn tanh(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the hyperbolic tangent of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn get_exponent(&self) -> Option<Exponent>

Returns exponent of self or None if self is Inf or NaN.

pub fn get_precision(&self) -> Option<usize>

Returns the number of significant bits used in the mantissa or None if self is Inf or NaN. Normal numbers use all bits of the mantissa. Subnormal numbers use fewer bits than the mantissa can hold.

pub fn max_value(p: usize) -> Self

Returns the maximum value for the specified precision p: all bits of the mantissa are set to 1, the exponent has the maximum possible value, and the sign is positive. Precision is rounded upwards to the word size.

pub fn min_value(p: usize) -> Self

Returns the minimum value for the specified precision p: all bits of the mantissa are set to 1, the exponent has the maximum possible value, and the sign is negative. Precision is rounded upwards to the word size.

pub fn min_positive(p: usize) -> Self

Returns the minimum positive subnormal value for the specified precision p: only the least significant bit of the mantissa is set to 1, the exponent has the minimum possible value, and the sign is positive. Precision is rounded upwards to the word size.

pub fn min_positive_normal(p: usize) -> Self

Returns the minimum positive normal value for the specified precision p: only the most significant bit of the mantissa is set to 1, the exponent has the minimum possible value, and the sign is positive. Precision is rounded upwards to the word size.

pub fn from_word(d: Word, p: usize) -> Self

Returns a new number with value d and the precision p. Precision is rounded upwards to the word size.

pub fn neg(&self) -> Self

Returns a copy of the number with the sign reversed.

pub fn to_raw_parts(&self) -> Option<(&[Word], usize, Sign, Exponent)>

Decomposes self into raw parts. The function returns a reference to a slice of words representing mantissa, numbers of significant bits in the mantissa, sign, and exponent.

pub fn from_raw_parts(m: &[Word], n: usize, s: Sign, e: Exponent) -> Self

Constructs a number from the raw parts:

• m is the mantisaa.
• n is the number of significant bits in mantissa.
• s is the sign.
• e is the exponent.

This function returns NaN in the following situations:

• n is larger than the number of bits in m.
• n is smaller than the number of bits in m, but m does not represent corresponding subnormal number mantissa.
• n is smaller than the number of bits in m, but e is not the minimum possible exponent.
• n or the size of m is too large (larger than isize::MAX / 2 + EXPONENT_MIN).

pub fn from_words(m: &[Word], s: Sign, e: Exponent) -> Self

Constructs a number from the slice of words:

• m is the mantissa.
• s is the sign.
• e is the exponent.

pub fn get_sign(&self) -> Option<Sign>

Returns the sign of self or None if self is NaN.

pub fn set_exponent(&mut self, e: Exponent)

Sets the exponent of self. Note that if self is subnormal, the exponent may not change, but the mantissa will shift instead. See example below.

Examples

use astro_float::BigFloat;
use astro_float::EXPONENT_MIN;

// construct a subnormal value.
let mut n = BigFloat::min_positive(128);

assert_eq!(n.get_exponent().unwrap(), EXPONENT_MIN);
assert_eq!(n.get_precision().unwrap(), 1);

// increase exponent.
n.set_exponent(n.get_exponent().unwrap() + 1);

// the outcome for subnormal number.
assert_eq!(n.get_exponent().unwrap(), EXPONENT_MIN);
assert_eq!(n.get_precision().unwrap(), 2);

pub fn get_mantissa_max_bit_len(&self) -> Option<usize>

Returns the maximum mantissa length of self in bits regardless of whether self is normal or subnormal.

pub fn set_precision(&mut self, p: usize, rm: RoundingMode) -> Result<(), Error>

Sets the precision of self to p. If the new precision is smaller than the existing one, the number is rounded using specified rounding mode rm.

Errors

• MemoryAllocation: failed to allocate memory for mantissa.
• InvalidArgument: the precision is incorrect.

pub fn reciprocal(&self, p: usize, rm: RoundingMode) -> Self

Computes the reciprocal of a number with precision p. The result is rounded using the rounding mode rm. Precision is rounded upwards to the word size.

pub fn set_sign(&mut self, s: Sign)

Sets the sign of self.

pub fn get_mantissa_digits(&self) -> Option<&[Word]>

Returns the raw mantissa words of a number.

pub fn convert_from_radix(
    sign: Sign,
    digits: &[u8],
    e: Exponent,
    rdx: Radix,
    p: usize,
    rm: RoundingMode
) -> Self

Converts an array of digits in radix rdx to BigFloat with precision p. digits represents mantissa and is interpreted as a number smaller than 1 and greater or equal to 1/rdx. The first element in digits is the most significant digit. e is the exponent part of the number, such that the number can be represented as digits * rdx ^ e. Precision is rounded upwards to the word size.

Examples

Code below converts -0.1234567₈ × 10₈^3₈ given in radix 8 to BigFloat.

use astro_float::{BigFloat, Sign, RoundingMode, Radix};

let g = BigFloat::convert_from_radix(
    Sign::Neg,
    &[1, 2, 3, 4, 5, 6, 7, 0],
    3,
    Radix::Oct,
    64,
    RoundingMode::None);

let n = BigFloat::from_f64(-83.591552734375, 64);

assert!(n.cmp(&g) == Some(0));

Errors

On error, the function returns NaN with the following associated error:

• MemoryAllocation: failed to allocate memory for mantissa.
• ExponentOverflow: the resulting exponent becomes greater than the maximum allowed value for the exponent.
• InvalidArgument: the precision is incorrect, or digits contains unacceptable digits for given radix.

pub fn convert_to_radix(
    &self,
    rdx: Radix,
    rm: RoundingMode
) -> Result<(Sign, Vec<u8>, Exponent), Error>

Converts self to radix rdx using rounding mode rm. The function returns sign, mantissa digits in radix rdx, and exponent such that the converted number can be represented as mantissa digits * rdx ^ exponent. The first element in the mantissa is the most significant digit.

Examples

use astro_float::{BigFloat, Sign, RoundingMode, Radix};

let n = BigFloat::from_f64(0.00012345678f64, 64);

let (s, m, e) = n.convert_to_radix(Radix::Dec, RoundingMode::None).unwrap();

assert_eq!(s, Sign::Pos);
assert_eq!(m, [1, 2, 3, 4, 5, 6, 7, 8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 5, 5, 4, 2]);
assert_eq!(e, -3);

Errors

• MemoryAllocation: failed to allocate memory for mantissa.
• ExponentOverflow: the resulting exponent becomes greater than the maximum allowed value for the exponent.
• InvalidArgument: self is Inf or NaN.

impl BigFloat

pub fn abs(&self) -> Self

Returns the absolute value of self.

pub fn int(&self) -> Self

Returns the integer part of self.

pub fn fract(&self) -> Self

Returns the fractional part of self.

pub fn ceil(&self) -> Self

Returns the smallest integer greater than or equal to self.

pub fn floor(&self) -> Self

Returns the largest integer less than or equal to self.

pub fn round(&self, n: usize, rm: RoundingMode) -> Self

Returns the rounded number with n binary positions in the fractional part of the number using rounding mode rm.

pub fn sqrt(&self, p: usize, rm: RoundingMode) -> Self

Computes the square root of a number with precision p. The result is rounded using the rounding mode rm. Precision is rounded upwards to the word size.

pub fn cbrt(&self, p: usize, rm: RoundingMode) -> Self

Computes the cube root of a number with precision p. The result is rounded using the rounding mode rm. Precision is rounded upwards to the word size.

pub fn ln(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the natural logarithm of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn log2(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the logarithm base 2 of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn log10(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the logarithm base 10 of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn exp(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes e to the power of self with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn sin(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the sine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn cos(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the cosine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn tan(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the tangent of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn asin(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the arcsine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn acos(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the arccosine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn sinh(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the hyperbolic sine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn cosh(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the hyperbolic cosine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn asinh(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the hyperbolic arcsine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn acosh(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the hyperbolic arccosine of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

pub fn atanh(&self, p: usize, rm: RoundingMode, cc: &mut Consts) -> Self

Computes the hyperbolic arctangent of a number with precision p. The result is rounded using the rounding mode rm. This function requires constants cache cc for computing the result. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_i8(i: i8, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_i16(i: i16, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_i32(i: i32, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_i64(i: i64, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_i128(i: i128, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_u8(i: u8, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_u16(i: u16, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_u32(i: u32, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_u64(i: u64, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

impl BigFloat

pub fn from_u128(i: u128, p: usize) -> Self

Constructs BigFloat with precision p from an integer value i. Precision is rounded upwards to the word size.

Trait Implementations

impl Binary for BigFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Clone for BigFloat

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BigFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BigFloat

fn default() -> BigFloat

Returns the “default value” for a type.

impl Display for BigFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<BigFloatNumber> for BigFloat

fn from(x: BigFloatNumber) -> Self

Converts to this type from the input type.

impl From<f32> for BigFloat

fn from(f: f32) -> Self

Converts to this type from the input type.

impl From<f64> for BigFloat

fn from(f: f64) -> Self

Converts to this type from the input type.

impl FromStr for BigFloat

fn from_str(src: &str) -> Result<BigFloat, Self::Err>

Returns parsed number or NAN in case of error.

type Err = ()

The associated error which can be returned from parsing.

impl Neg for &BigFloat

type Output = BigFloat

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Neg for BigFloat

type Output = BigFloat

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Octal for BigFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a> PartialEq<&'a BigFloat> for BigFloat

fn eq(&self, other: &&'a BigFloat) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<BigFloat> for BigFloat

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialOrd<&'a BigFloat> for BigFloat

fn partial_cmp(&self, other: &&'a BigFloat) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<BigFloat> for BigFloat

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl UpperHex for BigFloat

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Eq for BigFloat