// ---------------------------------------------------------------------------
// Result finalisation and precision rounding.
// ---------------------------------------------------------------------------
///|
/// Finalise a `Decimal` result under the active context: round to
/// `precision`, then enforce the exponent range. Non-finite results pass
/// through unchanged.
///
/// Flags raised here:
/// * `rounded` — whenever precision-driven adjustment shortened the
/// coefficient.
/// * `inexact` — when that shortening discarded non-zero digits, or when
/// overflow truncated a finite result.
/// * `overflow` — when the rounded result's adjusted exponent exceeds
/// `e_max`. Per GDA the result then becomes `±Infinity` or the
/// largest-finite-representable value, depending on the rounding mode.
///
fn Decimal::finalize_raw(self : Decimal, ctx : Context) -> Decimal {
match self.class {
Finite => {
// Capture the operand's adjusted exponent *before* rounding so the
// subnormal check uses the GDA-defined "pre-round adj < e_min"
// rule. Without this, results that round up to the e_min boundary
// (e.g., 0.999E-999 → 1.00E-999 at precision 3) would miss
// Subnormal/Underflow because their post-round adj equals e_min.
let pre_adj = if self.coefficient.is_zero() {
0
} else {
adjusted_exponent(self)
}
check_range(round_finite(self, ctx), pre_adj, ctx)
}
_ => self
}
}
///|
/// Apply the exponent-range rules to an already-rounded finite. Three
/// stages:
///
/// * Overflow (GDA §9.5.1) — non-zero result with `adjusted > e_max` goes
/// to `±Infinity` or the largest representable, depending on rounding.
/// * Subnormal-side etiny clamp — a result with `exponent < etiny` whose
/// coefficient is zero gets its exponent lifted to etiny and `Clamped`
/// raised. This is *unconditional*: the GDA spec treats the etiny floor
/// as a representability invariant, distinct from the `clamp` opt-in.
/// * Overflow-side clamp (GDA §9.5.3) — when `ctx.clamp` is on, finite
/// results with `exponent > etop` get the exponent folded down to etop
/// by padding the coefficient.
///
/// Non-zero subnormal results need no re-rounding here: `round_finite`
/// already folds the etiny floor into its single rounding pass (dropping
/// `max(precision, etiny)` digits at once), so the value reaching this
/// function is correctly rounded and only needs `apply_subnormal` to raise
/// the Subnormal / Underflow flags.
fn check_range(d : Decimal, pre_adj : Int32, ctx : Context) -> Decimal {
if ctx.precision == 0 {
return d
}
if d.coefficient.is_zero() {
let etiny = ctx.etiny()
if d.exponent < etiny {
ctx.raise_clamped()
return { ..d, exponent: etiny, }
}
if d.exponent > ctx.e_max {
ctx.raise_clamped()
return { ..d, exponent: ctx.e_max, }
}
// A zero that arose from underflow rounding still needs the
// Subnormal / Underflow / Clamped trio raised — the *pre-round*
// operand was subnormal, even though the rounded result is exactly
// zero at etiny.
if pre_adj < ctx.e_min {
ctx.raise_subnormal()
if ctx.flags.inexact {
ctx.raise_underflow()
}
ctx.raise_clamped()
}
return if ctx.clamp { apply_clamp(d, ctx) } else { d }
}
let adj = adjusted_exponent(d)
if adj > ctx.e_max {
return apply_overflow(d, ctx)
}
// Subnormal status is decided by the *pre-round* adjusted exponent
// (GDA §9.5.2): a result whose unrounded value sat below e_min is
// subnormal even when the rounded coefficient happens to land at
// adj == e_min (e.g., 0.999E-999 → 1.00E-999 at precision 3).
if pre_adj < ctx.e_min {
return apply_subnormal(d, ctx)
}
if ctx.clamp {
apply_clamp(d, ctx)
} else {
d
}
}
///|
/// Mark a subnormal result and raise associated flags. `round_finite`
/// already pushed the rounding past both the precision and etiny cuts,
/// so this is purely a flag-raising step — no re-rounding.
fn apply_subnormal(d : Decimal, ctx : Context) -> Decimal {
ctx.raise_subnormal()
// Underflow fires when the subnormal result is also inexact (raised
// upstream by round_finite when non-zero digits were discarded).
if ctx.flags.inexact {
ctx.raise_underflow()
}
// If the rounding collapsed the value to zero at the etiny floor, the
// etiny clamp rule fires alongside Subnormal.
if d.coefficient.is_zero() {
ctx.raise_clamped()
}
d
}
///|
/// GDA §9.5.3 clamp. When the result's exponent exceeds `etop`, fold it
/// down to `etop` by multiplying the coefficient by `10^(exp - etop)`, and
/// raise `clamped`. The numeric value is preserved (trailing zeros land in
/// the coefficient instead of the exponent), but the resulting coefficient
/// may exceed `precision` digits — which is fine, since the IEEE-754
/// formats define the storable digit count to *include* the padding.
fn apply_clamp(d : Decimal, ctx : Context) -> Decimal {
let etop = ctx.etop()
if d.exponent <= etop {
return d
}
let pad = d.exponent - etop
ctx.raise_clamped()
{ ..d, coefficient: scale_up(d.coefficient, pad), exponent: etop, }
}
///|
/// GDA §9.5.1 overflow. The rounding mode picks between `±Infinity` and
/// the largest finite representable (`(10^precision - 1) × 10^etop`,
/// `etop = e_max - precision + 1`). `overflow`, `inexact`, and `rounded` all
/// fire.
fn apply_overflow(d : Decimal, ctx : Context) -> Decimal {
ctx.raise_overflow()
ctx.raise_inexact()
ctx.raise_rounded()
let to_inf = match ctx.rounding {
HalfUp | HalfEven | HalfDown | Up => true
Ceiling => !d.negative
Floor => d.negative
Down | ZeroFiveUp => false
}
if to_inf {
signed_infinity(d.negative)
} else {
let etop = ctx.etop()
{
class: Finite,
negative: d.negative,
coefficient: pow10(ctx.precision) - 1N,
exponent: etop,
}
}
}
///|
/// The finite rounding path. Decides how many digits to drop based on
/// *both* the precision cap and the etiny floor — taking the larger of
/// the two so a single rounding pass produces a result that already
/// satisfies both constraints, avoiding the double-rounding bias from
/// rounding to precision and then re-rounding to etiny separately.
///
/// e.g., `1.52445E-80` with precision 5 and etiny -83:
/// * Precision alone would drop 1 digit (six → five) and round half-up
/// to `1.5245E-80`, then a subsequent subnormal pass would drop one
/// more and round to `1.525E-80`.
/// * Combined drop is 2 digits, rounding `1.52445E-80` once gives
/// `1.524E-80` (the correctly-rounded subnormal result).
fn round_finite(d : Decimal, ctx : Context) -> Decimal {
if ctx.precision == 0 {
return d
}
// Zero coefficients have nothing to round; the etiny / e_max exponent
// clamp lives in check_range's zero branch, where it surfaces Clamped
// rather than Rounded.
if d.coefficient.is_zero() {
return d
}
let n = digit_count(d.coefficient)
let prec_drop = if n > ctx.precision { n - ctx.precision } else { 0 }
let etiny = ctx.etiny()
let sub_drop = if etiny > d.exponent { etiny - d.exponent } else { 0 }
let dropped_len = if prec_drop > sub_drop { prec_drop } else { sub_drop }
if dropped_len == 0 {
return d
}
// Short-circuit: if every digit lies past the drop point (`dropped_len >
// n`), `pow10(dropped_len)` would explode for cases like
// `multiply(0.1, 9E-999999998)` where the natural exponent (-999999999)
// sits a billion places below etiny. The first-dropped-digit is then a
// leading zero (the coefficient is padded on the left to dropped_len),
// so we can decide round_decision by hand without materialising any
// big factor.
if dropped_len > n {
// The coefficient is non-zero here (zero returns early above), so every
// mode that ever rounds away from zero does so, and the discard is inexact.
let round_up = match ctx.rounding {
Up | ZeroFiveUp => true
Ceiling => !d.negative
Floor => d.negative
_ => false
}
let candidate : BigInt = if round_up { 1N } else { 0N }
ctx.raise_rounded()
ctx.raise_inexact()
return { ..d, coefficient: candidate, exponent: etiny, }
}
let divisor = pow10(dropped_len)
let kept = d.coefficient / divisor
let dropped = d.coefficient % divisor
let round_up = round_decision(
dropped,
dropped_len,
kept,
d.negative,
ctx.rounding,
)
let candidate = if round_up { kept + 1N } else { kept }
// 999 → 1000: candidate gained a digit. Check via digit count rather
// than `candidate >= pow10(precision)` — the latter materialises a
// huge BigInt when precision is large (e.g. multiply.decTest has
// sections with precision 999_999, where pow10(999_999) is a
// million-digit number).
let (final_coeff, extra) = if digit_count(candidate) > ctx.precision {
(candidate / 10N, 1)
} else {
(candidate, 0)
}
let new_exp = d.exponent + dropped_len + extra
ctx.raise_rounded()
if !dropped.is_zero() {
ctx.raise_inexact()
}
{ ..d, coefficient: final_coeff, exponent: new_exp, }
}
///|
/// Decide whether to round the kept coefficient up by one, working entirely
/// on the BigInt `dropped` value. The "first dropped digit" and "non-zero
/// remainder" predicates that the rounding modes need can be recovered from
/// `dropped` and its width `dropped_len` without ever going through a string.
/// Decide whether to round the kept value up by one, given the rounding `mode`,
/// the sign, a `half` indicator (`-1` below, `0` exactly at, `+1` above the
/// halfway point) and whether any non-zero digit was discarded. Shared by the
/// general rounding path and integer division.
fn should_round_up(
kept : BigInt,
negative : Bool,
half : Int32,
dropped_nonzero : Bool,
mode : Rounding,
) -> Bool {
match mode {
Down => false
Up => dropped_nonzero
HalfUp => half >= 0
HalfDown => half > 0
HalfEven =>
if half != 0 {
half > 0
} else {
// Exact tie — round so the kept value's last digit is even.
(kept % 2N).to_int() != 0
}
Ceiling => !negative && dropped_nonzero
Floor => negative && dropped_nonzero
ZeroFiveUp => {
let last = (kept % 10N).to_int()
(last == 0 || last == 5) && dropped_nonzero
}
}
}
///|
/// Decide rounding from a discarded tail `dropped` of width `dropped_len`,
/// deriving the half indicator and the non-zero flag, then delegating to
/// `should_round_up`.
fn round_decision(
dropped : BigInt,
dropped_len : Int32,
kept : BigInt,
negative : Bool,
mode : Rounding,
) -> Bool {
if dropped_len == 0 {
return false
}
// `dropped` may have leading zeros relative to `dropped_len` — e.g. when
// the original coefficient ended in zeros — so the "first dropped digit"
// is the *most significant* of the `dropped_len` written-out digits, not
// of `dropped` itself.
let top_divisor = pow10(dropped_len - 1)
let first_digit = (dropped / top_divisor).to_int()
let rest = dropped % top_divisor
let rest_nonzero = !rest.is_zero()
let dropped_nonzero = first_digit != 0 || rest_nonzero
// half indicator: -1 below halfway, 0 exactly halfway, +1 above.
let half = if first_digit > 5 {
1
} else if first_digit < 5 {
-1
} else if rest_nonzero {
1
} else {
0
}
should_round_up(kept, negative, half, dropped_nonzero, mode)
}
///|
/// Drop the low `drop_len` digits of `coef` under rounding `mode`, returning
/// `(candidate, kept, dropped)`: the rounded high part, the truncated high
/// part, and the discarded low part. Callers apply their own flag policy.
///
/// When the drop spans the whole coefficient (`drop_len >= digit_count`) the
/// kept part is zero and the discarded tail is the entire coefficient. This
/// path is taken without materialising `pow10(drop_len)`, which would explode
/// for the extreme exponent gaps `quantize` / `to-integral` admit (a target
/// tens of millions of places below the value). The leading written-out
/// dropped digit is the coefficient's own leading digit when the drop exactly
/// spans it, and a left-pad zero when it overshoots.
fn round_drop(
coef : BigInt,
drop_len : Int32,
negative : Bool,
mode : Rounding,
) -> (BigInt, BigInt, BigInt) {
if !coef.is_zero() {
let n = digit_count(coef)
if drop_len >= n {
let top = pow10(n - 1)
let first_digit = if drop_len == n { (coef / top).to_int() } else { 0 }
let rest_nonzero = drop_len > n || !(coef % top).is_zero()
let dropped_nonzero = first_digit != 0 || rest_nonzero
let half = if first_digit > 5 {
1
} else if first_digit < 5 {
-1
} else if rest_nonzero {
1
} else {
0
}
let candidate : BigInt = if should_round_up(
0N, negative, half, dropped_nonzero, mode,
) {
1N
} else {
0N
}
return (candidate, 0N, coef)
}
}
let divisor = pow10(drop_len)
let kept = coef / divisor
let dropped = coef % divisor
let candidate = if round_decision(dropped, drop_len, kept, negative, mode) {
kept + 1N
} else {
kept
}
(candidate, kept, dropped)
}
///|
/// Finalize `self` under `ctx` — round to precision and enforce the exponent
/// range — returning the result paired with the `Flags` it raised.
/// See `finalize_raw` for the algorithm.
pub fn Decimal::finalize(self : Decimal, ctx : Context) -> (Decimal, Flags) {
let ctx = { ..ctx, flags: Flags::new(), }
(self.finalize_raw(ctx), ctx.flags)
}