# math.big-integer

Exact whole-number arithmetic with no size limit worth mentioning, for the
calculations where 64 bits run out: a monthly loan compounds (1 + r) over 300
periods, and the exact fraction behind the payment has numerators thousands of
digits long. Money and rates in this registry are integers, so exactness is
available if the integers are allowed to be big.

Numbers travel as decimal strings ("-123", "0", "98765..."), because that is
the one form all three languages read and write identically: a JavaScript
number stops being exact at 2^53.

## Operations

- `add`, `subtract`, `multiply`: exact.
- `divide`: the quotient truncated towards zero, so -7 / 2 is -3.
- `remainder`: takes the sign of the dividend, so -7 rem 2 is -1 and
  a = (a / b) × b + (a rem b) always holds. This is TypeScript's and Rust's
  rule; Python floors by default and is adjusted to agree.
- `power`: the exponent is 0 or more; 0^0 is 1.

## Limits

`power` refuses a result that would exceed 65,536 bits (about 19,700 decimal
digits) before building it, estimated as bits(base) × exponent, the same way in
every language, so a slip of the exponent fails at once instead of hanging.
The other operations have no limit beyond memory and time; the Rust side is
schoolbook multiplication and shift-subtract division, which is quadratic.

## Why a capability, and what it exports

TypeScript (`bigint`) and Python (`int`) have arbitrary-precision integers
built in. Rust's standard library does not, and the registry takes no crates,
so the Rust module is a real implementation: it exports a `BigInt` type
(`from_i64`, `from_i128`, `add`, `sub`, `mul`, `div_rem`, `pow`, `to_i64`,
`to_i128`, `div_rem_small`, ordering and `Display`) that other capabilities build on, plus
`parse_big_integer` and `power_big_integer`. TypeScript and Python export
`parseBigInteger` / `parse_big_integer` and `powerBigInteger` /
`power_big_integer` over their native integers.

Numbers must be in canonical form: an optional "-", then digits with no leading
zero. "-0", "+1", "01", " 1" and "1.0" are errors, not guesses.