// ---------------------------------------------------------------------------
// next-plus / next-minus / next-toward: walk the representable lattice.
//
// next-plus returns the smallest representable value strictly greater than
// the operand (within the active context's precision and exponent range);
// next-minus is its mirror. next-toward picks the direction based on which
// of the two operands is larger numerically. IEEE-754 names these
// nextUp / nextDown.
// ---------------------------------------------------------------------------

///|
/// GDA `next-plus`: smallest representable value greater than `self`.
pub fn Decimal::next_plus(self : Decimal, ctx : Context) -> (Decimal, Flags) {
  let ctx = { ..ctx, flags: Flags::new(), }
  (self.next_plus_raw(ctx), ctx.flags)
}

///|
/// Internal worker for `next_plus`: returns the value, raising into `ctx.flags`.
fn Decimal::next_plus_raw(self : Decimal, ctx : Context) -> Decimal {
  match self.class {
    SNaN => quiet_snan(self, ctx)
    QNaN => self
    Infinity => if self.negative { largest_finite(true, ctx) } else { self }
    Finite => next_step(self, ctx, true)
  }
}

///|
/// GDA `next-minus`: largest representable value less than `self`.
pub fn Decimal::next_minus(self : Decimal, ctx : Context) -> (Decimal, Flags) {
  let ctx = { ..ctx, flags: Flags::new(), }
  (self.next_minus_raw(ctx), ctx.flags)
}

///|
/// Internal worker for `next_minus`: returns the value, raising into `ctx.flags`.
fn Decimal::next_minus_raw(self : Decimal, ctx : Context) -> Decimal {
  match self.class {
    SNaN => quiet_snan(self, ctx)
    QNaN => self
    Infinity => if self.negative { self } else { largest_finite(false, ctx) }
    Finite => next_step(self, ctx, false)
  }
}

///|
/// GDA `next-toward`: walk `self` one ULP toward `other`. When the two
/// operands compare equal numerically, return `self` (with `other`'s sign
/// in the equal-zero case, per GDA's sign-of-zero rule for next-toward).
pub fn Decimal::next_toward(
  self : Decimal,
  other : Decimal,
  ctx : Context,
) -> (Decimal, Flags) {
  let ctx = { ..ctx, flags: Flags::new(), }
  (self.next_toward_raw(other, ctx), ctx.flags)
}

///|
/// Internal worker for `next_toward`: returns the value, raising into `ctx.flags`.
fn Decimal::next_toward_raw(
  self : Decimal,
  other : Decimal,
  ctx : Context,
) -> Decimal {
  match propagate_nan(self, other, ctx) {
    Some(d) => return d
    None => ()
  }
  let cmp = compare_numeric_int(self, other)
  if cmp == 0 {
    // Numerically equal — the value is unchanged but takes `other`'s sign, so
    // `nextToward(0.00, -0.0000)` yields `-0.00`, not `+0.00`. Quiet.
    return { ..self, negative: other.negative, }
  }
  // The step itself is quiet (`next_plus` / `next_minus`), but next-toward
  // additionally signals when the stepped result leaves the normal range:
  // Overflow on Infinity, and Subnormal / Underflow when the result is below
  // e_min (with Clamped when the step collapses to a signed zero at etiny).
  // Inexact / Rounded accompany those — the true next value sits infinitely
  // close, so reaching a representable one is a rounding. Normal-range steps
  // stay quiet.
  let stepped = if cmp < 0 {
    Decimal::next_plus_raw(self, ctx)
  } else {
    Decimal::next_minus_raw(self, ctx)
  }
  raise_next_toward_flags(stepped, ctx)
  stepped
}

///|
/// Raise the status flags for a `next-toward` result whose value left the
/// normal range. See `next_toward` for the rationale.
fn raise_next_toward_flags(result : Decimal, ctx : Context) -> Unit {
  match result.class {
    Infinity => {
      ctx.raise_overflow()
      ctx.raise_inexact()
      ctx.raise_rounded()
    }
    Finite =>
      if result.coefficient.is_zero() {
        // Stepped across zero to a signed zero pinned at etiny.
        ctx.raise_subnormal()
        ctx.raise_underflow()
        ctx.raise_inexact()
        ctx.raise_rounded()
        ctx.raise_clamped()
      } else if adjusted_exponent(result) < ctx.e_min {
        ctx.raise_subnormal()
        ctx.raise_underflow()
        ctx.raise_inexact()
        ctx.raise_rounded()
      }
    _ => ()
  }
}

///|
/// The largest finite representable: `(10^precision - 1) × 10^etop`.
fn largest_finite(negative : Bool, ctx : Context) -> Decimal {
  let etop = ctx.etop()
  {
    class: Finite,
    negative,
    coefficient: pow10(ctx.precision) - 1N,
    exponent: etop,
  }
}

///|
/// Smallest positive subnormal: `1 × 10^etiny`. The next step above zero.
fn smallest_subnormal(negative : Bool, ctx : Context) -> Decimal {
  let etiny = ctx.etiny()
  { class: Finite, negative, coefficient: 1N, exponent: etiny, }
}

///|
/// Unified step: `step_up == true` walks toward +∞ (next-plus), `false`
/// walks toward -∞ (next-minus). Routes through the sign-flipped helpers
/// so the directional logic lives in one place.
///
/// This is a *quiet* computation — it raises no status flags. `next-plus` /
/// `next-minus` are defined to be quiet; `next-toward` shares the same
/// stepping but raises its own flags from the result (see `next_toward`).
fn next_step(x : Decimal, ctx : Context, step_up : Bool) -> Decimal {
  if ctx.precision <= 0 {
    return invalid_nan(ctx)
  }
  // Zero special-case: next-plus(±0) = smallest +subnormal;
  // next-minus(±0) = smallest -subnormal. The input's sign is dropped.
  if x.coefficient.is_zero() {
    return smallest_subnormal(!step_up, ctx)
  }
  // Reduce to magnitude work: if the input is positive, "step up" walks
  // away from zero (increase magnitude) and "step down" walks toward zero
  // (decrease magnitude). For negative inputs the directions invert.
  let walking_away = (step_up && !x.negative) || (!step_up && x.negative)
  let stepped = if walking_away {
    step_magnitude_up(x.coefficient, x.exponent, ctx)
  } else {
    step_magnitude_down(x.coefficient, x.exponent, ctx)
  }
  match stepped {
    // Stepping past the largest representable lands on a signed Infinity.
    Overflow => signed_infinity(x.negative)
    // Magnitude stepped to zero — a signed zero at etiny on the opposite side
    // (next-plus(-tiny) → -0; next-minus(tiny) → +0).
    Zero => finite_zero(ctx.etiny(), x.negative)
    Value(coef, exp) =>
      { class: Finite, negative: x.negative, coefficient: coef, exponent: exp, }
  }
}

///|
/// Outcome of a magnitude step: a concrete next value, or the "we went
/// past the largest representable" / "we went past zero" boundary.
priv enum StepResult {
  Value(BigInt, Int32)
  Overflow
  Zero
}

///|
/// Step the magnitude `coef × 10^exp` up by 1 ULP under the active
/// precision / exponent range. The input is assumed positive and non-zero.
///
/// Over-precision inputs first round Ceiling-style (round toward larger
/// magnitude); if the rounding moved the value, that's already the
/// next-up. Otherwise the rounded result has its low digit incremented.
fn step_magnitude_up(coef : BigInt, exp : Int32, ctx : Context) -> StepResult {
  let etop = ctx.etop()
  let etiny = ctx.etiny()
  let n = digit_count(coef)
  let adj = exp + n - 1
  // Below-tininess: smallest representable above zero.
  if adj < etiny {
    return Value(1N, etiny)
  }
  // Over-precision: Ceiling-style round, returning early if rounding
  // actually moved the value upward.
  let (c0, e0) = if n > ctx.precision {
    let drop = n - ctx.precision
    let divisor = pow10(drop)
    let kept = coef / divisor
    let dropped = coef % divisor
    let new_exp = exp + drop
    if !dropped.is_zero() {
      let candidate = kept + 1N
      let cap = pow10(ctx.precision)
      if candidate >= cap {
        let bumped = new_exp + 1
        if bumped > etop {
          return Overflow
        }
        return Value(candidate / 10N, bumped)
      }
      return Value(candidate, new_exp)
    }
    (kept, new_exp)
  } else {
    (coef, exp)
  }
  // At precision: pad if allowed, then add 1 ULP.
  let (c, e) = normalise_for_step(c0, e0, ctx.precision, etiny)
  let new_coef = c + 1N
  let cap = pow10(ctx.precision)
  if new_coef >= cap {
    let bumped_exp = e + 1
    if bumped_exp > etop {
      return Overflow
    }
    return Value(new_coef / 10N, bumped_exp)
  }
  Value(new_coef, e)
}

///|
/// Step the magnitude `coef × 10^exp` down by 1 ULP. Symmetric to
/// `step_magnitude_up`; the boundary case is the precision-floor crossing
/// (10^(p-1) → 10^p - 1 at exp - 1).
///
/// Over-precision inputs first Floor-truncate (drop the excess digits);
/// the truncated value is strictly less than the original, so that *is*
/// the next-down.
fn step_magnitude_down(coef : BigInt, exp : Int32, ctx : Context) -> StepResult {
  let etiny = ctx.etiny()
  let n = digit_count(coef)
  let adj = exp + n - 1
  if adj < etiny {
    return Zero
  }
  let (c0, e0) = if n > ctx.precision {
    let drop = n - ctx.precision
    let divisor = pow10(drop)
    let kept = coef / divisor
    let dropped = coef % divisor
    let new_exp = exp + drop
    if !dropped.is_zero() {
      // Floor truncation already produced a value below the original.
      return Value(kept, new_exp)
    }
    (kept, new_exp)
  } else {
    (coef, exp)
  }
  let (c, e) = normalise_for_step(c0, e0, ctx.precision, etiny)
  let cap_min = pow10(ctx.precision - 1)
  if c == cap_min && e > etiny {
    return Value(pow10(ctx.precision) - 1N, e - 1)
  }
  let new_coef = c - 1N
  if new_coef.is_zero() {
    return Zero
  }
  Value(new_coef, e)
}

///|
/// Pad the coefficient with trailing zeros (lowering the exponent) so it
/// reaches `precision` digits — but never fall below `etiny`. Inputs whose
/// natural digit count already exceeds precision are returned as-is; the
/// boundary handling in `step_magnitude_up` / `step_magnitude_down` deals
/// with the wraparound at that point.
fn normalise_for_step(
  coef : BigInt,
  exp : Int32,
  precision : Int32,
  etiny : Int32,
) -> (BigInt, Int32) {
  let n = digit_count(coef)
  if n >= precision {
    return (coef, exp)
  }
  let pad_max = exp - etiny
  if pad_max <= 0 {
    return (coef, exp)
  }
  let pad = if precision - n < pad_max { precision - n } else { pad_max }
  (coef * pow10(pad), exp - pad)
}