Struct BigNumeric

Source

pub struct BigNumeric { /* private fields */ }

Expand description

An arbitrary-precision decimal: (-1)^neg · (Σ limbs[i]·BASE^i) · 10^-scale. limbs is little-endian with no trailing (most-significant) zero limbs; the value zero is the empty limb vector with neg == false.

Implementations§

Source §

impl BigNumeric

Source

pub fn is_zero(&self) -> bool

True when the magnitude is zero (regardless of sign / scale).

Source

pub fn scale(&self) -> u16

Source

pub fn parts(&self) -> (bool, &[u32], u16)

v7.38 (read01, T3.C3) — expose the on-disk parts (sign, base-10^9 limbs little-endian, scale) for the codec.

Source

pub fn from_parts(neg: bool, limbs: Vec<u32>, scale: u16) -> Self

Rebuild from codec parts. Normalizes (a canonical big value never has a mantissa that fits i128 — the caller collapses those to Numeric).

Source

pub fn from_i128(v: i128, scale: u16) -> Self

Build from an i128 mantissa at a given scale.

Source

pub fn to_i128(&self) -> Option<i128>

Convert back to (i128 mantissa, scale) when the mantissa fits; None on overflow (the caller keeps the big form). Scale is preserved.

Source

pub fn cmp(&self, other: &Self) -> Ordering

Signed comparison honoring sign + scale.

Deliberately NOT Ord: this compares numeric VALUE (it aligns the two scales first, so 1.5 and 1.50 are Equal), while the derived PartialEq / Eq compare the representation field-wise and call those two unequal. Ord requires a == b iff a.cmp(b) == Equal, so an Ord impl here would be unsound-by-contract. Keep the inherent method.

Source

pub fn div_rem_int(&self, other: &Self) -> (Self, Self)

Signed integer division truncating toward zero (like i128 / i128), ignoring scale. Returns (quotient, remainder).

Source

pub fn div(&self, other: &Self, result_scale: u16) -> Option<Self>

Fixed-point division to a target result_scale, rounded half-away-from- zero — the shape PG’s numeric / numeric uses. Errors are the caller’s: dividing by zero returns None.

Source

pub fn sqrt(&self, result_scale: u16) -> Option<Self>

v7.38 (read01, C4) — square root at a target display scale, rounded half-away-from-zero, the shape PG’s numeric sqrt uses. None for a negative value (the caller raises the domain error). The caller picks result_scale (PG’s ~16-significant-digit rule) and guarantees it is at least the argument’s own scale.

Source

pub fn round_to(&self, target_scale: u16) -> Self

v7.38 (S1.1b) — round to target_scale, half-away-from-zero (PG numeric round_var). Widening pads with zeros; narrowing drops digits with rounding.

Source

pub fn exp(&self) -> Self

v7.38 (S1.1b) — e^self at PG’s numeric display scale (~16 significant digits), rounded half-away. Range-reduces by halving until the operand is small (fast Taylor convergence), sums the series with guard digits, then squares back. The final scale keys off the RESULT magnitude, so it is computed at high precision first, then rounded. Matches PG18.4 to the last digit across the differential set.

Source

pub fn pow_numeric(&self, exp: &Self) -> Option<Self>

v7.38 (S1.1b) — self^exp for a positive base and any exponent, exact to PG’s numeric display scale, via exp(exp · ln(self)). ln is taken at high internal precision (not its display scale) so the composition keeps ~16 correct significant digits. None for a non-positive base.

Source

pub fn ln(&self) -> Option<Self>

v7.38 (S1.1b) — natural log at a target display scale, rounded half-away. None for a non-positive value (the caller raises the domain error). Range-reduces x = m · 2^e to m ∈ [2/3, 4/3) where the atanh series converges fast, then adds e · ln2. Matches PG18.4 to the last digit.

Source

pub fn log_base(&self, base: &Self) -> Option<Self>

v7.38 (read01) — PG numeric log(base, x) = ln(x) / ln(base), computed at a wide working scale and then rounded to PG’s display scale. None when either operand is non-positive (ln_at rejects it) or when ln(base) is zero (base = 1) — the caller raises PG’s specific “logarithm of zero / of a negative number” / “division by zero” error.

Source