Struct UnsignedNumeric

Source

pub struct UnsignedNumeric {
    pub value: InnerUint,
}

Expand description

A UnsignedNumeric is an unsigned 192-bit fixed-point number with 18 decimal places of precision.

§Internal Representation

Internally, the value is stored as a InnerUint, which wraps a little-endian array [u64; 3]. This means the layout is:

InnerUint([lo, mid, hi])
// equivalent to:
// value = lo + (mid << 64) + (hi << 128)

Each component contributes to the full 192-bit value:

value = (hi × 2^128) + (mid × 2^64) + lo

§Fixed-Point Scaling

All values are scaled by ONE (10^18). That is, the internal number is interpreted as raw / ONE to recover its real-world value.

Examples:

InnerUint([1_000_000_000_000_000_000, 0, 0]) → 1.0
InnerUint([500_000_000_000_000_000, 0, 0]) → 0.5
InnerUint([2_000_000_000_000_000_000, 0, 0]) → 2.0

§Example: High-Bit Usage

When you write:

let a = UnsignedNumeric::from([0, 0, 1]);

This initializes the internal 192-bit value with the array [0, 0, 1]. In this representation:

0 is the least significant 64 bits (lo)
0 is the middle 64 bits (mid)
1 is the most significant 64 bits (hi)

The actual 192-bit value is computed as:

value = (1 × 2^128) + (0 × 2^64) + 0 = 2^128
      = 340282366920938463463374607431768211456

Since this is a fixed-point number, the real-world value is:

real_value = value / 10^18 = 340282366920938463463.374607431768211456

This system allows for both extremely high precision and a vast dynamic range, making UnsignedNumeric ideal for financial, scientific, or blockchain applications where f64 or even u128 would lose accuracy or overflow.

Fields§

§value: InnerUint

Internal value stored as a 192-bit integer, scaled by ONE (10^18).

Implementations§

Source §

impl UnsignedNumeric

Source

pub fn zero() -> Self

Returns a UnsignedNumeric representing 0.0.

Source

pub fn one() -> Self

Returns a UnsignedNumeric representing 1.0.

Source

pub fn new(value: u128) -> Self

Constructs a UnsignedNumeric from an integer value by scaling it by ONE (10^18). For example, new(7) produces 7.0.

Source

pub fn from_scaled_u128(value: u128) -> Self

Constructs a UnsignedNumeric from a u128 that is already scaled by ONE (i.e. in fixed-point space). This bypasses internal multiplication and is useful for constants or pre-scaled data.

Source

pub fn from_values(lo: u64, mid: u64, hi: u64) -> Self

Constructs a UnsignedNumeric directly from a raw [u64; 3] value. The input is interpreted as already scaled (fixed-point). Layout is little-endian: [lo, mid, hi] = lo + (mid << 64) + (hi << 128).

Source

pub fn to_bytes(&self) -> [u8; 24]

Converts this UnsignedNumeric into a raw [u8; 24] representation.

Source

pub fn from_bytes(bytes: &[u8; 24]) -> Self

Converts a raw [u8; 24] representation into a UnsignedNumeric.

Source

pub fn to_imprecise(&self) -> Option<u128>

Converts this UnsignedNumeric into a regular u128 by dividing by ONE. Applies rounding correction to avoid always flooring the result. Returns None if the division would overflow or the result exceeds u128::MAX.

Source

pub fn signed(&self) -> SignedNumeric

Converts this UnsignedNumeric into a signed version, wrapping it in a SignedNumeric with is_negative = false. Useful when beginning arithmetic that may result in negative values.

Source

pub fn almost_eq(&self, rhs: &Self, precision: InnerUint) -> bool

Compares two UnsignedNumerics for approximate equality, allowing for a configurable precision window.

Source

pub fn less_than(&self, rhs: &Self) -> bool

Returns true if self < rhs in fixed-point terms.

Source

pub fn greater_than(&self, rhs: &Self) -> bool

Returns true if self > rhs.

Source

pub fn less_than_or_equal(&self, rhs: &Self) -> bool

Returns true if self <= rhs.

Source

pub fn greater_than_or_equal(&self, rhs: &Self) -> bool

Returns true if self >= rhs.

Source

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

Rounds down to the nearest whole number by truncating fractional digits.

Source

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

Rounds up to the nearest whole number.

Source

pub fn checked_div(&self, rhs: &Self) -> Option<Self>

Divides self / rhs in fixed-point space, maintaining precision. Applies rounding correction to minimize truncation error. Returns None on divide-by-zero or overflow.

Source

pub fn checked_mul(&self, rhs: &Self) -> Option<Self>

Multiplies two UnsignedNumerics and returns the result in fixed-point space. Automatically divides by ONE to maintain correct scaling, and applies rounding correction. Falls back to a reduced-precision path if full multiplication would overflow.

Source

pub fn checked_add(&self, rhs: &Self) -> Option<Self>

Adds two precise numbers. Returns None on overflow.

Source

pub fn checked_sub(&self, rhs: &Self) -> Option<Self>

Subtracts rhs from self. Returns None if the result would be negative.

Source

pub fn unsigned_sub(&self, rhs: &Self) -> (Self, bool)

Computes the absolute difference between two numbers. Returns the result and a boolean indicating whether the result was originally negative.

Source

pub fn to_string(&self) -> String

Converts the precise number into a human-readable decimal string with full 18-digit precision.

For example, a number representing 3.1415 will be displayed as: "3.141500000000000000"

Source §

impl UnsignedNumeric

Source

pub fn frexp(&self) -> Option<(Self, i64)>

Frexp breaks f into a normalized fraction and an integral power of two. It returns frac and exp satisfying f == frac × 2**exp, with the absolute value of frac in the interval [½, 1).

Special cases are: Frexp(±0) = ±0, 0 Frexp(±Inf) = ±Inf, 0 Frexp(NaN) = NaN, 0

Source

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

Raises self to the power of exp, returning the result as a new UnsignedNumeric. Returns None if the operation would overflow or if self is zero.

b = pow/frac y = a^b ln (y) = bln (a) y = e^(b ln (a))

Source