nova-bignum overview

nova-bignum is an arbitrary-precision numbers package for Nova: BigInt (unbounded integers), BigRat (exact rationals), BigDecimal (arbitrary-precision decimal), and BigFloat (arbitrary-precision binary floating point) — a counterpart to Python’s int/decimal/fractions, Rust’s num-bigint/num-rational, and Go’s math/big.

All four types are value-records: a copy is a small stack header (a sign plus a slice/pointer), the limb/mantissa data lives on the GC heap and is shared across copies, and immutability means no operation ever mutates a value another binding still holds. BigDecimal, BigFloat, and BigRat each expose their arithmetic through Nova’s operators and methods (see each type’s page for exactly which operators apply and when a context or Result is required); under the hood every one of them is built on top of BigInt and delegates its arithmetic to it.

The family, at a glance

When to use which

• Need an integer wider than i128, with no fractional part ever? BigInt.
• Need a fraction that stays exact forever — no drift after a thousand operations? BigRat.
• Need decimal semantics (money, prices, anything a human reads in base 10) with an explicit, controllable rounding policy? BigDecimal.
• Need f64-like binary floating point but with more precision than 53 significant bits, and you’re fine reasoning in base 2? BigFloat.

Conversions between family members follow one rule everywhere: exact directions need no context; lossy directions require an explicit MathContext (decimal) or PrecisionContext (binary) — there is no hidden rounding anywhere in the package. BigInt → BigRat/BigDecimal is always exact; BigDecimal → BigRat and BigFloat → BigRat are exact (a decimal or binary fraction is always representable as an exact rational); BigRat → BigDecimal, BigRat → BigFloat, and BigDecimal ↔ BigFloat are lossy and take a context.

Minimal example

import bignum.{Sign, ParseNumberError}
import bignum.bigint.{BigInt, DivError}

ro a = 42.to_bigint()
ro b = "12345678901234567890".to_bigint()!!
assert(a + b > a)

Module map

Errors as values

Two failure shapes recur across the whole family:

• Division by zero. BigInt/BigRat return it as a value — Result[_, DivError] with the single variant DivisionByZero. BigDecimal/BigFloat panic on it instead (parity with the primitive int/f64 division-by-zero contract) — it is a design choice for those two types, not an oversight.
• String parsing. Every str @to_bigint()/@to_bigdecimal()/ @to_bigfloat()/@to_bigrat() returns Result[_, ParseNumberError], one shared enum for the whole package (Empty, OnlySign, InvalidCharacter, MultiplePoints, MultipleExponents, EmptyExponent, EmptyMantissa, ZeroDenominator) — no per-type variant or adapter.

panic is reserved for internal invariants and for the division-by-zero/ sqrt-of-negative contracts noted above — never for a value the caller handed in through a Result-returning API.

Contents of this doc set

• bigint.md — BigInt: representation, arithmetic, Karatsuba multiplication, Knuth Algorithm D division, bounds
• bigdecimal.md — BigDecimal: scale, RoundingMode, MathContext
• bigfloat.md — BigFloat: mantissa/exponent, precision, f64 conversions
• bigrat.md — BigRat: exact fractions, normal form, bridges to BigDecimal/BigFloat

Related documents

• README.md — package pitch, install, full feature/limits list
• docs/plans/235-bigint.md, 236-bigdecimal.md, 237-bigfloat.md, 240-bigrat.md, 243-*.md in the nova repo — the design plans this package implements
• src/bigint/core_test.nv, src/bigdecimal/core_test.nv, src/bigfloat/core_test.nv, src/bigrat/core_test.nv — the full test suites; every example in this doc set is adapted from one of them