envzn
0.8 · beta · not released

Library / Numbers / Numeric types / Decimal128

CLASS

Decimal128

The decimal128 primitive's backing value-class (V1).

Fields 2

int128 coefficient
int32 exponent

Constructors 2

INIT()

Default-initialize to zero (constitution I.D.i(b)).

INIT(int128 coeff, int32 exp)

Construct from a (coefficient, exponent) pair: value = coefficient × 10^exponent. The form the literal/conversion/arithmetic lowering targets.

Methods 28

METHOD powTen(int32 n) RETURNS int128
reads

10^n as int128, for 0 ≤ n ≤ 38 (callers keep n in range). n < 0 → 1.

METHOD digitCount(int128 v) RETURNS int32
reads

Decimal digit count of |v| (zero counts as 1 digit). Overflow-safe (uses ~/).

METHOD decideUp(int32 cmpHalf, boolean nonzeroDropped, boolean coeffOdd, boolean neg, RoundingMode mode) RETURNS boolean
reads

Single source of truth for "round the retained magnitude UP by one?" across all seven RoundingMode values, given a cohort-free description of what was dropped below the retained coefficient: - cmpHalf — the dropped fraction vs ½ ULP of the last retained digit: +1 above ½, 0 exactly ½ (a tie), −1 below ½. - nonzeroDropped — TRUE iff ANY nonzero digit was dropped (the directed modes UP/CEILING/FLOOR round on any remainder, not just at the half). - coeffOdd — parity of the retained coefficient (HALF_EVEN tie-break). - neg — sign of the value (CEILING/FLOOR are sign-directed). Every reducing path (reduced / mulReduce / divReduce / roundedDrop) funnels its rounding decision through here, so the bare operators' fixed (34, HALF_EVEN) behavior and the explicit-mode surface share one rule and cannot drift.

METHOD roundedDrop(boolean neg, int128 mag, int32 drop, RoundingMode mode) RETURNS int128
reads

Drop the drop lowest decimal digits (drop ≥ 1) from an EXACT magnitude mag, rounding per mode via decideUp, and return the rounded magnitude. The dropped part has no sticky tail (mag is exact), so the tie test is just remainder-vs-half. Used by roundTo (decimal-place rounding); the sig-digit reducers compute cmpHalf inline because they also carry a sticky direction.

METHOD reduced(boolean neg, int128 mag, int32 exp, int32 stickyDir, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Build a decimal128 from a sign + magnitude + exponent, rounding the magnitude to ≤ precision significant digits with the given mode. stickyDir carries information about digits below mag already dropped: +1 = the true value is slightly ABOVE mag (round up at a tie), −1 = slightly BELOW (round down at a tie), 0 = mag is exact (tie → per mode). Bare +/− pass (34, HALF_EVEN) so their behavior is unchanged.

METHOD addMagnitudes(int128 ca, int32 ea, int128 cb, int32 eb, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Sum of two decimals by sign+magnitude. Aligns the larger-exponent operand UP exactly (bounded so it fits int128), rounds the smaller operand DOWN to the working exponent capturing a tri-state sticky, combines by sign, then reduces to 34 digits. Subtraction's guard-borrow is handled by the sticky sign (a rounded-off subtrahend makes the true result slightly smaller).

METHOD pairDigits(int128 hPart, int128 lPart) RETURNS int32
reads

Product of two magnitudes (each < 10^34) at the given exponent, reduced to ≤ 34 digits with round-half-even. Avoids a 256-bit binary intermediate by splitting each coefficient at 10^17 into halves whose pairwise products all fit int128 (< 10^34 < 2^113); the exact 68-digit product is carried as a (high, low) decimal pair and reduced digit-by-digit with a sticky tail. Significant-digit count of a value carried as a (high, low) decimal pair hPart·10^34 + lPart, with lPart < 10^34. When the high part is nonzero its lowest digit sits at decimal position 34, so the pair spans digitCount(hPart) + 34 digits; otherwise the count is just lPart's. The 34 here is the structural split exponent (10^34), independent of the target precision.

METHOD mulReduce(boolean neg, int128 ma, int128 mb, int32 exp, int32 precision, RoundingMode mode) RETURNS decimal128
reads
METHOD divReduce(boolean neg, int128 ma, int128 mb, int32 exp, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Quotient of two magnitudes (mb ≠ 0) at the given exponent, to 34 significant digits with round-half-even. Schoolbook long division: take the integer quotient, then emit fractional digits one at a time (each step rem*10 < 10^35 stays in int128) until 34 significant digits or an exact remainder, then one guard digit + sticky for the final rounding.

METHOD equals(decimal128 other) RETURNS boolean
reads

Cohort-normalized VALUE equality (the Equatable surface a == b): two decimals are equal iff their numeric values match, regardless of cohort — 1.0 == 1.00 == 1. Computed as (a − b) having a zero coefficient (the subtraction aligns + reduces exactly), so different representations of the same value compare equal.

METHOD isLessThan(decimal128 other) RETURNS boolean
reads

Strict less-than (the Comparable surface): the sign of (a − b).

METHOD hash() RETURNS uint64
reads

Cohort-invariant hash (the Hashable surface): hashes the CANONICAL form (coefficient with trailing zeros stripped + adjusted exponent), so equal values hash equal — the invariant that makes decimal128 a sound Dictionary/ Set key. FNV-1a over the canonical (coefficient, exponent). The int128 → uint64 folds are inline unchecked narrowings (Decimal128 is a floor primitive, emitted before NumericUtilities, so it can't call it).

METHOD __op_plus__(decimal128 other) RETURNS decimal128
reads
METHOD __op_minus__(decimal128 other) RETURNS decimal128
reads
METHOD negate() RETURNS decimal128
reads

Negation — -d lowers to this (decimal128 has no C++ unary operator-). Flip the coefficient's sign and keep the exponent: exact, never rounded, and the cohort survives — -(1.50) is -1.50, which 0 - d through addMagnitudes would not promise.

METHOD checkedExp(int64 e) RETURNS int32
reads

Narrow a working exponent (computed in int64 to dodge int32 overflow UB) back to the int32 exponent field, raising a recoverable MathError when the scale overflows int32 — decision 2's "PANIC MathError on overflow". Reachable: d = d * d doubles the exponent each step, so ~32 squarings overflow. Decimal128 is emitted before the MathError class, so it cannot PANIC MathError directly — it routes through the int128 floor-division domain trap (INT64_MIN ~/ −1 → "floor division result out of range"), the only MathError raiser reachable from a floor primitive. (The message is the generic floor-div one; an exponent-specific message would need the MathError class reordered ahead of Decimal128 — see decimal128-design.md.)

METHOD __op_times__(decimal128 other) RETURNS decimal128
reads
METHOD __op_divide__(decimal128 other) RETURNS decimal128
reads
METHOD clampPrecision(int32 p) RETURNS int32
reads

Clamp a caller-supplied precision to the type's valid range [1, 34]: decimal128 carries at most 34 significant digits, and a precision below 1 is meaningless. Out-of-range requests are pinned to the nearest bound rather than rejected — the result is always a well-formed decimal128.

METHOD roundTo(int32 places, RoundingMode mode) RETURNS decimal128
reads

Round to places digits after the decimal point, ties broken per mode. Negative places rounds to tens / hundreds / … (place −2 → nearest 100). A value already at this granularity or coarser is returned unchanged. This is decimal-PLACE rounding (the everyday money/measurement operation); significant-digit control is the precision arg on the arithmetic methods.

METHOD roundTo(int32 places) RETURNS decimal128
reads

roundTo with the default HALF_EVEN (banker's) tie-break.

METHOD add(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Sum reduced to precision significant digits, ties per mode — the explicit-context form of +.

METHOD subtract(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Difference reduced to precision significant digits, ties per mode — the explicit-context form of −.

METHOD multiply(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Product reduced to precision significant digits, ties per mode — the explicit-context form of *.

METHOD divide(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128
reads

Quotient to precision significant digits, ties per mode — the explicit-context form of /. Divide-by-zero raises MathError through divReduce's floor-division, exactly as / does.

METHOD absOf(decimal128 v) RETURNS decimal128
reads

|v| — magnitude as a decimal128 (negate the coefficient, keep the exponent). The cohort is irrelevant to closeTo (it compares values), so no normalization is needed.

METHOD closeTo(decimal128 other) RETURNS boolean
reads

Approximate equality — the ≈ (U+2248) / ≉ (U+2249) surface. decimal128 is EXACT and 34 significant digits wide, so the number type's √machine-eps epsilon (1.5e-8, sized for float64) is far too coarse here. closeTo is RELATIVE (a fraction of the larger magnitude): the default tolerance agrees to ~30 of 34 significant digits — it absorbs a few ULP of rounding noise from /, AS, … without calling genuinely different values close. Use ->isClose(other, rtol, atol) for a caller-chosen tolerance.

METHOD isClose(decimal128 other, decimal128 rtol, decimal128 atol) RETURNS boolean
reads

closeTo with caller-chosen relative + absolute tolerances (the principled- tolerance companion, parallel to number->isClose): TRUE iff |a − b| ≤ max(rtol·max(|a|,|b|), atol). rtol scales with the larger operand magnitude (the relative term); atol is the absolute floor near zero (where a relative test alone never matches a non-zero value).