// ---------------------------------------------------------------------------
// Arithmetic context: precision, rounding mode, accumulated status flags.
//
// This file introduces the arithmetic context shared by arithmetic operations.
// ---------------------------------------------------------------------------

///|
/// GDA rounding modes for finite-result finalisation.
pub(all) enum Rounding {
  /// Round to nearest; on tie, round away from zero.
  HalfUp
  /// Round to nearest; on tie, round to the even kept-coefficient digit.
  /// IEEE 754 default; minimises bias across many round operations.
  HalfEven
  /// Round to nearest; on tie, round toward zero.
  HalfDown
  /// Always round away from zero.
  Up
  /// Always round toward zero (truncation).
  Down
  /// Round toward `+Infinity`.
  Ceiling
  /// Round toward `-Infinity`.
  Floor
  /// Round-half-to-even — but only kick in when the kept coefficient's last
  /// digit is `0` or `5`. Used in legal/financial contexts.
  ZeroFiveUp
} derive(Eq)

///|
pub impl Show for Rounding with fn to_string(self) {
  match self {
    HalfUp => "half_up"
    HalfEven => "half_even"
    HalfDown => "half_down"
    Up => "up"
    Down => "down"
    Ceiling => "ceiling"
    Floor => "floor"
    ZeroFiveUp => "05up"
  }
}

///|
/// GDA status flags accumulated by Context-aware ops. All flags are set
/// additively (never cleared by an op); a sequence of ops reports whether
/// any of them triggered the signal.
pub(all) struct Flags {
  mut inexact : Bool
  mut rounded : Bool
  mut invalid_operation : Bool
  mut division_by_zero : Bool
  mut overflow : Bool
  mut underflow : Bool
  mut subnormal : Bool
  mut clamped : Bool
  /// Raised by `from_string` (GDA `to-number`) when the input doesn't match the
  /// GDA grammar: the result is a quiet NaN and this flag is set. (`parse`
  /// instead reports a syntax error as a catchable `ParseError`.)
  mut conversion_syntax : Bool
  /// Raised by integer division when the quotient would exceed precision
  /// (`Decimal::divide_int` with a multi-precision quotient), and by
  /// quantize when the rescaled coefficient exceeds precision.
  mut division_impossible : Bool
  /// Raised by `0 / 0` and Infinity-arithmetic special cases where the
  /// result has no defined value.
  mut division_undefined : Bool
  /// Reserved for context-internal allocation failures. Kept for GDA-tag
  /// compatibility but not yet emitted by any op.
  mut insufficient_storage : Bool
  /// Raised by the arbitrary-precision mathematical functions (`exp`, `ln`,
  /// `log10`, `power`) when the active context is unsuitable for them —
  /// `precision`, `e_max`, or `e_min` exceeds the `MAX_MATH` bound, or a
  /// `power` integer exponent is out of range. Per GDA these
  /// operations must refuse (returning NaN) rather than attempt a
  /// computation that cannot converge in bounded work.
  mut invalid_context : Bool
} derive(Eq)

///|
/// A fresh `Flags` with every signal cleared.
pub fn Flags::new() -> Flags {
  {
    inexact: false,
    rounded: false,
    invalid_operation: false,
    division_by_zero: false,
    overflow: false,
    underflow: false,
    subnormal: false,
    clamped: false,
    conversion_syntax: false,
    division_impossible: false,
    division_undefined: false,
    insufficient_storage: false,
    invalid_context: false,
  }
}

///|
/// Combine two flag sets — the union of every raised signal.
pub fn Flags::combine(self : Flags, other : Flags) -> Flags {
  {
    inexact: self.inexact || other.inexact,
    rounded: self.rounded || other.rounded,
    invalid_operation: self.invalid_operation || other.invalid_operation,
    division_by_zero: self.division_by_zero || other.division_by_zero,
    overflow: self.overflow || other.overflow,
    underflow: self.underflow || other.underflow,
    subnormal: self.subnormal || other.subnormal,
    clamped: self.clamped || other.clamped,
    conversion_syntax: self.conversion_syntax || other.conversion_syntax,
    division_impossible: self.division_impossible || other.division_impossible,
    division_undefined: self.division_undefined || other.division_undefined,
    insufficient_storage: self.insufficient_storage ||
    other.insufficient_storage,
    invalid_context: self.invalid_context || other.invalid_context,
  }
}

///|
/// Arithmetic context — precision, rounding mode, and exponent range.
///
/// Context is immutable configuration: operations take a `Context`, never
/// mutate it, and return their result paired with the `Flags` they raised.
/// (The `flags` field below is a per-call scratch accumulator; a caller's own
/// `Context` value is never written to.)
///
/// `precision == 0` means "no precision limit": the op produces an exact
/// result with as many digits as needed. This is the default so the existing
/// "exact" arithmetic surface keeps its current behaviour.
pub struct Context {
  precision : Int32
  rounding : Rounding
  e_min : Int32
  e_max : Int32
  /// When set, finite results with `exponent > etop = e_max - precision + 1`
  /// get their exponent folded down to `etop` by padding the coefficient
  /// with trailing zeros, and `clamped` is raised. Required for IEEE-754
  /// decimal{32,64,128} conformance; off by default so the bare GDA
  /// arithmetic surface preserves trailing-zero scale.
  clamp : Bool
  flags : Flags
}

///|
/// Build a Context. Defaults: no precision cap, half-to-even rounding,
/// near-`Int.max` exponent range (effectively unbounded for dectest's range),
/// no clamp.
///
/// Panics if `precision < 0` or `e_min > e_max` — these are API-misuse
/// (typically literal typos), so they fail fast rather than returning an error.
pub fn Context::new(
  precision~ : Int32 = 0,
  rounding~ : Rounding = HalfEven,
  e_min~ : Int32 = -999_999_999,
  e_max~ : Int32 = 999_999_999,
  clamp~ : Bool = false,
) -> Context {
  guard precision >= 0 else {
    abort("Context::new: precision must be non-negative")
  }
  guard e_min <= e_max else {
    abort("Context::new: e_min must not exceed e_max")
  }
  { precision, rounding, e_min, e_max, clamp, flags: Flags::new(), }
}

///|
/// Convenience: a context that performs no rounding and lets every result
/// pass through exactly. Mostly useful as a sentinel for "give me exact
/// arithmetic" callers.
pub fn Context::exact() -> Context {
  Context::new()
}

///|
/// The smallest exponent of a representable (subnormal) value: `e_min -
/// precision + 1`. Coefficients below this floor round to zero.
fn Context::etiny(self : Context) -> Int32 {
  self.e_min - self.precision + 1
}

///|
/// The largest exponent a finite result may carry before clamping: `e_max -
/// precision + 1`. Above it, trailing zeros are folded into the coefficient.
fn Context::etop(self : Context) -> Int32 {
  self.e_max - self.precision + 1
}

///|
/// IEEE-754 `decimal32` preset: precision 7, `Emax = 96`, `Emin = -95`,
/// `clamp = true`, rounding half-even.
pub fn Context::decimal32() -> Context {
  Context::new(precision=7, rounding=HalfEven, e_max=96, e_min=-95, clamp=true)
}

///|
/// IEEE-754 `decimal64` preset: precision 16, `Emax = 384`,
/// `Emin = -383`, `clamp = true`.
pub fn Context::decimal64() -> Context {
  Context::new(
    precision=16,
    rounding=HalfEven,
    e_max=384,
    e_min=-383,
    clamp=true,
  )
}

///|
/// IEEE-754 `decimal128` preset: precision 34, `Emax = 6144`,
/// `Emin = -6143`, `clamp = true`.
pub fn Context::decimal128() -> Context {
  Context::new(
    precision=34,
    rounding=HalfEven,
    e_max=6144,
    e_min=-6143,
    clamp=true,
  )
}

///|
/// Raise status flags on the context. Flags are additive and never clear an
/// existing signal; these helpers make the side-channel explicit at call sites.
fn Context::raise_inexact(self : Context) -> Unit {
  self.flags.inexact = true
}

///|
fn Context::raise_rounded(self : Context) -> Unit {
  self.flags.rounded = true
}

///|
fn Context::raise_invalid_operation(self : Context) -> Unit {
  self.flags.invalid_operation = true
}

///|
fn Context::raise_division_by_zero(self : Context) -> Unit {
  self.flags.division_by_zero = true
}

///|
fn Context::raise_overflow(self : Context) -> Unit {
  self.flags.overflow = true
}

///|
fn Context::raise_underflow(self : Context) -> Unit {
  self.flags.underflow = true
}

///|
fn Context::raise_subnormal(self : Context) -> Unit {
  self.flags.subnormal = true
}

///|
fn Context::raise_clamped(self : Context) -> Unit {
  self.flags.clamped = true
}

///|
fn Context::raise_division_undefined(self : Context) -> Unit {
  self.flags.division_undefined = true
}

///|
fn Context::raise_division_impossible(self : Context) -> Unit {
  self.flags.division_impossible = true
}

///|
fn Context::raise_invalid_context(self : Context) -> Unit {
  self.flags.invalid_context = true
}