Library / Numbers / Numeric types / Decimal128
Decimal128
The decimal128 primitive's backing value-class (V1).
Fields 2
int128 coefficientint32 exponentConstructors 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 int128reads
10^n as int128, for 0 ≤ n ≤ 38 (callers keep n in range). n < 0 → 1.
METHOD digitCount(int128 v) RETURNS int32reads
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 booleanreads
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 int128reads
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 decimal128reads
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 decimal128reads
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 int32reads
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 decimal128reads
METHOD divReduce(boolean neg, int128 ma, int128 mb, int32 exp, int32 precision, RoundingMode mode) RETURNS decimal128reads
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 booleanreads
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 booleanreads
Strict less-than (the Comparable surface): the sign of (a − b).
METHOD hash() RETURNS uint64reads
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 decimal128reads
METHOD __op_minus__(decimal128 other) RETURNS decimal128reads
METHOD negate() RETURNS decimal128reads
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 int32reads
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 decimal128reads
METHOD __op_divide__(decimal128 other) RETURNS decimal128reads
METHOD clampPrecision(int32 p) RETURNS int32reads
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 decimal128reads
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 decimal128reads
roundTo with the default HALF_EVEN (banker's) tie-break.
METHOD add(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128reads
Sum reduced to precision significant digits, ties per mode — the
explicit-context form of +.
METHOD subtract(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128reads
Difference reduced to precision significant digits, ties per mode —
the explicit-context form of −.
METHOD multiply(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128reads
Product reduced to precision significant digits, ties per mode — the
explicit-context form of *.
METHOD divide(decimal128 other, int32 precision, RoundingMode mode) RETURNS decimal128reads
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 decimal128reads
|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 booleanreads
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 booleanreads
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).