Module numeric 

The numeric tower’s foundation: a hand-rolled arbitrary-precision integer.

Logos carries the type of a number across every boundary (interpreter, VM, wire), so an integer never silently becomes an IEEE-754 double the way a JSON number does — there is no 2^53 cliff here. BigInt is the exact, unbounded integer all of that rests on; Rational/Decimal/Complex build on it.

Representation is sign + little-endian base-2^64 magnitude (limbs, no trailing zeros; zero is the empty magnitude). A single-limb magnitude is stored inline — no heap allocation for anything that fits 64 bits, and the add/mul/div_rem fast paths compute those cases in machine registers. Arithmetic here is correct first — schoolbook add/sub/mul and bit-at-a-time long division — which is the exact-determinism floor; Karatsuba multiplication and Knuth-D division are the FAST follow-up that must reproduce these results bit-for-bit.

Structs

BigInt

An exact, arbitrary-precision integer.

Complex

An exact complex number re + im·i, each part a Rational. Because the parts are exact, i·i == −1 and (1+i)(1−i) == 2 hold with no floating error, and the Gaussian rationals are closed under + − × ÷ (every nonzero value has an exact inverse). The magnitude √(re²+im²) is irrational in general — request it as an f64 view via Complex::abs_f64 rather than forcing the exact value inexact.

Decimal

An exact base-10 fixed-point number: an integer coefficient divided by a power of ten. The value is coefficient · 10^(−scale), so 19.99 is coefficient = 1999, scale = 2. Money lives here — 0.1 + 0.2 is exactly 0.3, never the 0.30000000000000004 of a binary float, and a long ledger of sums never drifts.

Modular

An element of the ring ℤ/nℤ — an integer taken modulo a fixed modulus. This is the arbitrary-modulus generalisation of crate::Word8/…/crate::Word64 (whose modulus is a power of two): arithmetic WRAPS into [0, modulus), the cyclic group where overflow is the point, not a bug. The number-theory / crypto substrate — modular exponentiation and the extended-Euclid inverse live here, so RSA-style and finite-field code is exact.

Rational

An exact rational number: a fraction kept in lowest terms with a strictly positive denominator. Built on BigInt, so it never rounds the way a JSON / f64 “number” does — 1/3 stays exactly 1/3, not 0.3333…, and a numerator past 2^53 survives instead of collapsing onto a double.

Enums

RoundingMode

How a Decimal resolves the digits it must drop when rounding to a smaller scale. HalfEven (banker’s rounding) is the money/finance default: the unbiased tie-break that does not drift a long column of sums upward.

Constants

NUMERIC_HASH_P

The Mersenne prime 2^61 − 1: the modulus of the UNIFIED numeric hash. Every numeric type hashes to its mathematical value mod P, so values that compare equal across types (1 == 1.0 == 1/1) hash equal — the hash/ equality coherence law that lets mixed-type map keys unify.

Functions

cmp_bigint_f64_exact

Exact comparison of a BigInt against an f64. None iff f is NaN.

cmp_i64_f64_exact

Exact comparison of an i64 against an f64. None iff f is NaN.

cmp_rational_f64_exact

Exact comparison of a Rational against an f64. None iff f is NaN.

numeric_hash_bigint

The unified numeric hash of a BigInt. Limbs fold most-significant first: 2^64 ≡ 8 (mod 2^61 − 1).

numeric_hash_f64

The unified numeric hash of an f64: m · 2^e mod P via modular exponentiation (2^61 ≡ 1, so the exponent reduces mod 61). NaN and the infinities take fixed sentinels outside the finite-value pattern.

numeric_hash_i64

The unified numeric hash of an i64 (its value mod P, sign-adjusted).

numeric_hash_rational

The unified numeric hash of a Rational: num · den⁻¹ mod P (Fermat inverse; P is prime, and a reduced denominator is never ≡ 0 mod P for representable values).

rational_from_f64_exact

The EXACT rational value of a finite f64. None for NaN/±inf.