pub struct Repr<const BASE: u64> { /* private fields */ }Expand description
Underlying representation of an arbitrary precision floating number.
The floating point number is represented as significand * base^exponent, where the
type of the significand is IBig, and the type of exponent is isize. The representation
is always normalized (nonzero signficand is not divisible by the base, or zero signficand
with zero exponent).
When it’s used together with a Context, its precision will be limited so that
|significand| < base^precision. As an intentional exception, the result of an inexact
addition or subtraction may carry one extra guard digit, so |significand| can be up to
base^(precision+1); the guard digit is what lets a much-smaller operand be reduced to a
sign-only sticky bit during alignment without mis-rounding.
§Infinity and signed zero
Special values are encoded with a zero significand and a sentinel exponent:
- value zero (
+0): exponent = 0 - negative zero (
-0): exponent = -1 - positive infinity (
+inf): exponent =isize::MAX - negative infinity (
-inf): exponent =isize::MIN
The infinities are only supposed to be consumed as sentinels: only equality test and
comparison are implemented for them, and any arithmetic operation that takes an infinity
as input will lead to panic (at the FBig layer) or return an error (at the Context
layer). If an operation result is too large or too small, the operation will return an
infinity (as a value) at the Context layer, or panic at the FBig layer.
Implementations§
Source§impl<const B: u64> Repr<B>
impl<const B: u64> Repr<B>
Sourcepub fn to_f32(&self) -> Approximation<f32, Rounding>
pub fn to_f32(&self) -> Approximation<f32, Rounding>
Convert the float number representation to a f32 with the default IEEE 754 rounding mode.
The default IEEE 754 rounding mode is HalfEven (rounding to nearest, ties to even). To convert the float number with a specific rounding mode, please use FBig::to_f32.
§Examples
assert_eq!(Repr::<2>::one().to_f32(), Exact(1.0));
assert_eq!(Repr::<10>::infinity().to_f32(), Inexact(f32::INFINITY, NoOp));Sourcepub fn to_f64(&self) -> Approximation<f64, Rounding>
pub fn to_f64(&self) -> Approximation<f64, Rounding>
Convert the float number representation to a f64 with the default IEEE 754 rounding mode.
The default IEEE 754 rounding mode is HalfEven (rounding to nearest, ties to even). To convert the float number with a specific rounding mode, please use FBig::to_f64.
§Examples
assert_eq!(Repr::<2>::one().to_f64(), Exact(1.0));
assert_eq!(Repr::<10>::infinity().to_f64(), Inexact(f64::INFINITY, NoOp));Sourcepub fn to_int(&self) -> Approximation<IBig, Rounding>
pub fn to_int(&self) -> Approximation<IBig, Rounding>
Convert the float number representation to a IBig.
The fractional part is always rounded to zero. To convert with other rounding modes, please use FBig::to_int().
§Warning
If the float number has a very large exponent, it will be evaluated and result in allocating an huge integer and it might eat up all your memory.
To get a rough idea of how big the number is, it’s recommended to use EstimatedLog2.
§Examples
assert_eq!(Repr::<2>::neg_one().to_int(), Exact(IBig::NEG_ONE));§Panics
Panics if the number is infinte.
Source§impl<const B: u64> Repr<B>
impl<const B: u64> Repr<B>
Sourcepub const fn neg_infinity() -> Repr<B>
pub const fn neg_infinity() -> Repr<B>
Create a Repr instance representing the negative infinity
Sourcepub const fn neg_zero() -> Repr<B>
pub const fn neg_zero() -> Repr<B>
Create a Repr instance representing the negative zero (-0)
Negative zero is produced by operations (e.g. 1 / -inf, ceil(-0), cancellation
under round-toward-negative) and is distinct from +0 only in operations that are
sensitive to the sign of zero (e.g. 1 / -0 = -inf). It compares equal to +0.
Sourcepub const fn is_pos_zero(&self) -> bool
pub const fn is_pos_zero(&self) -> bool
Determine if the Repr represents positive zero (+0)
This returns true only for +0; use Self::is_neg_zero to detect -0, or check
self.significand().is_zero() to detect either signed zero.
§Examples
assert!(Repr::<2>::zero().is_pos_zero());
assert!(!Repr::<10>::neg_zero().is_pos_zero());
assert!(!Repr::<10>::one().is_pos_zero());Sourcepub const fn is_neg_zero(&self) -> bool
pub const fn is_neg_zero(&self) -> bool
Sourcepub const fn is_infinite(&self) -> bool
pub const fn is_infinite(&self) -> bool
Sourcepub fn is_int(&self) -> bool
pub fn is_int(&self) -> bool
Determine if the number can be regarded as an integer.
Note that this function returns false when the number is infinite.
§Examples
assert!(Repr::<2>::zero().is_int());
assert!(Repr::<10>::one().is_int());
assert!(!Repr::<16>::new(123.into(), -1).is_int());Sourcepub const fn sign(&self) -> Sign
pub const fn sign(&self) -> Sign
Get the sign of the number
Note that -0 has a negative sign (so 1 / -0 = -inf), while +0 has a positive sign.
§Examples
assert_eq!(Repr::<2>::zero().sign(), Sign::Positive);
assert_eq!(Repr::<2>::neg_zero().sign(), Sign::Negative);
assert_eq!(Repr::<2>::neg_one().sign(), Sign::Negative);
assert_eq!(Repr::<10>::neg_infinity().sign(), Sign::Negative);Sourcepub fn digits(&self) -> usize
pub fn digits(&self) -> usize
Get the number of digits (under base B) in the significand.
If the number is 0, then 0 is returned (instead of 1).
§Examples
assert_eq!(Repr::<2>::zero().digits(), 0);
assert_eq!(Repr::<2>::one().digits(), 1);
assert_eq!(Repr::<10>::one().digits(), 1);
assert_eq!(Repr::<10>::new(100.into(), 0).digits(), 1); // 1e2
assert_eq!(Repr::<10>::new(101.into(), 0).digits(), 3);Sourcepub fn new(significand: IBig, exponent: isize) -> Repr<B>
pub fn new(significand: IBig, exponent: isize) -> Repr<B>
Create a Repr from the significand and exponent. This constructor will normalize the representation.
§Examples
let a = Repr::<2>::new(400.into(), -2);
assert_eq!(a.significand(), &IBig::from(25));
assert_eq!(a.exponent(), 2);
let b = Repr::<10>::new(400.into(), -2);
assert_eq!(b.significand(), &IBig::from(4));
assert_eq!(b.exponent(), 0);Sourcepub fn significand(&self) -> &IBig
pub fn significand(&self) -> &IBig
Get the significand of the representation
Sourcepub fn into_parts(self) -> (IBig, isize)
pub fn into_parts(self) -> (IBig, isize)
Convert the float number into raw (signficand, exponent) parts
§Examples
use dashu_int::IBig;
let a = Repr::<2>::new(400.into(), -2);
assert_eq!(a.into_parts(), (IBig::from(25), 2));
let b = Repr::<10>::new(400.into(), -2);
assert_eq!(b.into_parts(), (IBig::from(4), 0));Source§impl<const B: u64> Repr<B>
impl<const B: u64> Repr<B>
Sourcepub fn num_hash_residue(&self) -> i128
pub fn num_hash_residue(&self) -> i128
The numeric-hash residue (mod 2¹²⁷−1) used by NumHash:
sgn(significand) · (|significand| mod M127) · (B^exponent mod M127).
Special values: +0 → 0, -0 → 0, +∞ → HASH_INF (= M127), -∞ → HASH_NEGINF
(= -M127), matching num-order’s f64::fhash. The subsequent i128::num_hash maps both
HASH_INF and HASH_NEGINF back to 0, so the final hash of ±∞ is 0 — but the
residue distinguishes them so that composite types (e.g. CBig) combine them algebraically
the same way num-order’s Complex<f64> does.