// ---------------------------------------------------------------------------
// Advanced mathematical functions: exp / ln / log10 / power.
//
// Each operation produces a correctly-rounded result by driving the
// fixed-point integer kernels in `math_kernel.mbt` (`dexp` / `dlog` / `dlog10` /
// `dpower`) inside a Ziv loop: compute to a few guard digits, and if the
// value sits exactly on a rounding boundary, widen the working precision by 3
// and retry until it rounds unambiguously. `finalize` then rounds to the
// context precision and raises Inexact / Rounded / Overflow / Underflow.
//
// exp(x) : analytic over/underflow screen, else `dexp`.
// ln(x) : `dlog`, seeded by `ln_exp_bound`.
// log10(x) : exact for powers of ten, else `dlog10`.
// power : 0/1/inf and integer special cases handled directly (exact
// square-and-multiply for in-range integer exponents); the
// general case is `dpower = dexp(y * dlog(x))`.
//
// `exp` / `ln` / `log10` always round half-even; `power` respects the context
// rounding mode. All four refuse contexts wider than the `MAX_MATH` limit
// (signalling Invalid_context), which also bounds the work they can do.
// ---------------------------------------------------------------------------
///|
/// `MAX_MATH`: the largest `precision` (and the bound on
/// `|e_max|` / `|e_min|`) for which the series-based mathematical functions
/// `exp` / `ln` / `log10` / `power` are defined. Beyond it the working
/// precision needed to round correctly would be unbounded, so GDA requires
/// the operation to refuse with `Invalid_context` rather than diverge.
const MAX_MATH : Int32 = 999_999
///|
/// True when `ctx` is too extreme for the series-based math functions:
/// `precision`, `e_max`, or `e_min` lies outside the `±MAX_MATH` window.
/// Such a context cannot bound the working precision the algorithms need,
/// so the op must signal `Invalid_context` and return NaN.
fn math_context_invalid(ctx : Context) -> Bool {
ctx.precision > MAX_MATH || ctx.e_max > MAX_MATH || ctx.e_min < -MAX_MATH
}
///|
/// True when a finite operand is outside the math functions' domain: with
/// `ed = exponent + digits` (one more than the
/// adjusted exponent), reject when `digits > MAX_MATH`, `ed > MAX_MATH + 1`, or
/// `ed < 2*(1 - MAX_MATH)`. The window is deliberately asymmetric — large
/// negative exponents are tolerated almost twice as far as large positive ones.
/// Such an operand can't be handled in bounded work, so the series-based
/// functions reject it with `Invalid_operation`.
fn operand_out_of_math_range(d : Decimal) -> Bool {
let digits = digit_count(d.coefficient)
let ed = d.exponent + digits
digits > MAX_MATH || ed > MAX_MATH + 1 || ed < 2 * (1 - MAX_MATH)
}
///|
/// Shared entry guard for the unary math functions (`exp` / `ln` / `log10`):
/// propagate a NaN operand (signalling and quietening on sNaN), then reject an
/// over-wide context with `Invalid_context`. Returns `Some(result)` when the
/// caller should short-circuit, `None` to continue with the real computation.
fn math_precheck(x : Decimal, ctx : Context) -> Decimal? {
match x.class {
SNaN => Some(quiet_snan(x, ctx))
QNaN => Some(x)
_ =>
if math_context_invalid(ctx) {
ctx.raise_invalid_context()
Some(Decimal::nan())
} else {
None
}
}
}
///|
/// GDA `exp`: e raised to the operand.
pub fn Decimal::exp(self : Decimal, ctx : Context) -> (Decimal, Flags) {
let ctx = { ..ctx, flags: Flags::new(), }
(self.exp_raw(ctx), ctx.flags)
}
///|
/// Internal worker for `exp`: returns the value, raising into `ctx.flags`.
fn Decimal::exp_raw(self : Decimal, ctx : Context) -> Decimal {
match math_precheck(self, ctx) {
Some(d) => return d
None => ()
}
match self.class {
Infinity =>
if self.negative {
// exp(-Inf) = +0
{ class: Finite, negative: false, coefficient: 0N, exponent: 0, }
} else {
self
}
Finite =>
if self.coefficient.is_zero() {
Decimal::one()
} else {
exp_finite(self, ctx)
}
_ => abort("Decimal::exp: NaN handled above")
}
}
///|
/// Number of decimal digits of a non-negative `Int` (`len(str(n))`).
fn int_digits(n : Int32) -> Int32 {
bigint_digits(BigInt::from_int(n))
}
///|
/// Finite non-zero `exp`.
///
/// Only a narrow band of adjusted exponents needs real work: outside it the
/// result either overflows, underflows to zero, or is indistinguishable from
/// 1 at the target precision. Those four boundary cases are produced directly
/// (as a value `finalize` will round and flag correctly); the general band runs
/// the correctly-rounded `dexp` kernel inside a Ziv loop that widens precision
/// until the result rounds unambiguously. The result is transcendental, hence
/// always inexact — `finalize` raises `Inexact` / `Rounded` for us, which is
/// why even `exp(1E-40) = 1.000000000` reports them.
fn exp_finite(x : Decimal, ctx : Context) -> Decimal {
let p = ctx.precision
let adj = adjusted_exponent(x)
let etiny = ctx.etiny()
let result : Decimal = if !x.negative && adj > int_digits((ctx.e_max + 1) * 3) {
// overflow: a value above e_max that finalize turns into ±Infinity.
{
class: Finite,
negative: false,
coefficient: 1N,
exponent: ctx.e_max + 1,
}
} else if x.negative && adj > int_digits((-etiny + 1) * 3) {
// underflow: a value below etiny that finalize rounds to 0.
{ class: Finite, negative: false, coefficient: 1N, exponent: etiny - 1, }
} else if !x.negative && adj < -p {
// just above 1: 1 + 10^-p, so finalize rounds to 1 and raises Inexact.
{
class: Finite,
negative: false,
coefficient: pow10(p) + 1N,
exponent: -p,
}
} else if x.negative && adj < -p - 1 {
// just below 1: (p+1) nines = 1 - 10^-(p+1); finalize rounds up to 1.
{
class: Finite,
negative: false,
coefficient: pow10(p + 1) - 1N,
exponent: -p - 1,
}
} else {
// General case: correctly-rounded dexp inside a Ziv loop.
let c = if x.negative { -x.coefficient } else { x.coefficient }
let (coeff, exp) = for extra = 3 {
let (coeff, exp) = dexp(c, x.exponent, p + extra)
// Roundable with any mode once coeff is not a multiple of the half-ulp.
if ziv_roundable(coeff, p) {
break (coeff, exp)
} else {
continue extra + 3
}
}
{ class: Finite, negative: false, coefficient: coeff, exponent: exp, }
}
// exp always rounds half-even; flags accumulate into the shared Flags.
result.finalize_raw({ ..ctx, rounding: HalfEven, })
}
///|
/// Lexicographic `<` on two ASCII digit strings, needed by the `ln` / `log10`
/// exponent-bound estimates. (A shorter
/// string that is a prefix of a longer one compares less.)
fn dstr_lt(a : String, b : String) -> Bool {
let la = a.length()
let lb = b.length()
let n = if la < lb { la } else { lb }
for i = 0 {
if i >= n {
break la < lb
} else {
let ca = a[i].to_int()
let cb = b[i].to_int()
if ca != cb {
break ca < cb
} else {
continue i + 1
}
}
}
}
///|
/// GDA `ln`: natural logarithm. ln(1) = 0; ln(x) for finite x > 0 uses
/// the atanh series plus range reduction; ln(0) = -Infinity (with
/// `Division_by_zero` raised); ln of negative or NaN is the usual
/// propagation / invalid.
pub fn Decimal::ln(self : Decimal, ctx : Context) -> (Decimal, Flags) {
let ctx = { ..ctx, flags: Flags::new(), }
(self.ln_raw(ctx), ctx.flags)
}
///|
/// Internal worker for `ln`: returns the value, raising into `ctx.flags`.
fn Decimal::ln_raw(self : Decimal, ctx : Context) -> Decimal {
match math_precheck(self, ctx) {
Some(d) => return d
None => ()
}
match self.class {
Infinity => if self.negative { invalid_nan(ctx) } else { self }
Finite =>
if self.coefficient.is_zero() {
// GDA: ln(0) = -Infinity, no flag raised. (Math-wise this is a
// limit, not a "1/0"-style division-by-zero, so unlike some C
// libraries' log we don't signal Division_by_zero.)
signed_infinity(true)
} else if self.negative {
invalid_nan(ctx)
} else if is_one(self) {
Decimal::zero()
} else {
ln_finite(self, ctx)
}
_ => abort("Decimal::ln: NaN handled above")
}
}
///|
/// True iff `x` is exactly the value 1 — regardless of how it's
/// represented (`1`, `1.0`, `1E+0`, `1.00000`). Cheaper than `compare` for
/// the early-exit `ln(1) = 0` and `power(1, y) = 1` checks.
fn is_one(x : Decimal) -> Bool {
if x.negative || !(x.class is Finite) || x.exponent > 0 {
return false
}
// x = 1 means coefficient = 10^(-exponent), which has exactly `1 - exponent`
// digits. Check the digit count first: this both rejects most operands
// cheaply and bounds `-exponent` to the coefficient's width, so we never
// materialise a `pow10` larger than the coefficient (a tiny value like
// `1E-999999999` would otherwise build a billion-digit power of ten here).
digit_count(x.coefficient) == 1 - x.exponent &&
x.coefficient == pow10(-x.exponent)
}
///|
/// Finite-positive `ln` (x != 1). Runs the correctly-rounded `dlog` kernel
/// inside a Ziv loop: start at `p - ln_exp_bound(x) + 2` fractional places
/// (enough that the leading digit of the result is captured) and widen by 3
/// until the value rounds unambiguously, then finalize half-even. The result
/// is irrational, hence always inexact.
fn ln_finite(x : Decimal, ctx : Context) -> Decimal {
let p = ctx.precision
let c = x.coefficient
let e = x.exponent
let (coeff, places) = for places = p - ln_exp_bound(x) + 2 {
let coeff = dlog(c, e, places)
if ziv_roundable(coeff, p) {
break (coeff, places)
} else {
continue places + 3
}
}
(
{
class: Finite,
negative: coeff < 0N,
coefficient: abs_big(coeff),
exponent: -places,
} : Decimal).finalize_raw({ ..ctx, rounding: HalfEven, })
}
///|
/// Lower bound `r` on the adjusted exponent of `ln(x)` (i.e. `|ln(x)| >=
/// 10^r`), used to seed the Ziv loop's working precision. Uses the bounds
/// `1 - 1/x <= ln(x) <= x - 1` for `0.1 <= x <= 10`.
fn ln_exp_bound(x : Decimal) -> Int32 {
let adj = adjusted_exponent(x)
if adj >= 1 {
return int_digits(adj * 23 / 10) - 1
}
if adj <= -2 {
return int_digits((-1 - adj) * 23 / 10) - 1
}
let c = x.coefficient
let e = x.exponent
if adj == 0 {
// 1 < x < 10
let num = (c - pow10(-e)).to_string()
let den = c.to_string()
num.length() - den.length() - (if dstr_lt(num, den) { 1 } else { 0 })
} else {
// adj == -1: 0.1 <= x < 1
e + (pow10(-e) - c).to_string().length() - 1
}
}
///|
/// GDA `log10`: common (base-10) logarithm. Built as `ln(x) / ln(10)`
/// at workp precision; falls back to the closed-form result for exact
/// powers of ten.
pub fn Decimal::log10(self : Decimal, ctx : Context) -> (Decimal, Flags) {
let ctx = { ..ctx, flags: Flags::new(), }
(self.log10_raw(ctx), ctx.flags)
}
///|
/// Internal worker for `log10`: returns the value, raising into `ctx.flags`.
fn Decimal::log10_raw(self : Decimal, ctx : Context) -> Decimal {
match math_precheck(self, ctx) {
Some(d) => return d
None => ()
}
match self.class {
Infinity => if self.negative { invalid_nan(ctx) } else { self }
Finite =>
if self.coefficient.is_zero() {
// GDA: log10(0) = -Infinity, no flag (matches ln(0)).
signed_infinity(true)
} else if self.negative {
invalid_nan(ctx)
} else {
log10_finite(self, ctx)
}
_ => abort("Decimal::log10: NaN handled above")
}
}
///|
/// Finite-positive `log10`. Exact powers of ten short-circuit to their
/// integer logarithm (the adjusted exponent); otherwise the correctly-rounded
/// `dlog10` kernel runs inside a Ziv loop, mirroring `ln_finite`.
fn log10_finite(x : Decimal, ctx : Context) -> Decimal {
match power_of_ten_log(x) {
// log10(10^k) = k; still finalized so it fits precision (may round).
Some(k) =>
return Decimal::from_int(k).finalize_raw({ ..ctx, rounding: HalfEven, })
None => ()
}
let p = ctx.precision
let c = x.coefficient
let e = x.exponent
let (coeff, places) = for places = p - log10_exp_bound(x) + 2 {
let coeff = dlog10(c, e, places)
if ziv_roundable(coeff, p) {
break (coeff, places)
} else {
continue places + 3
}
}
(
{
class: Finite,
negative: coeff < 0N,
coefficient: abs_big(coeff),
exponent: -places,
} : Decimal).finalize_raw({ ..ctx, rounding: HalfEven, })
}
///|
/// Lower bound on the adjusted exponent of `log10(x)`, seeding the Ziv loop.
fn log10_exp_bound(x : Decimal) -> Int32 {
let adj = adjusted_exponent(x)
if adj >= 1 {
return int_digits(adj) - 1
}
if adj <= -2 {
return int_digits(-1 - adj) - 1
}
let c = x.coefficient
let e = x.exponent
if adj == 0 {
// 1 < x < 10
let num = (c - pow10(-e)).to_string()
let den = (231N * c).to_string()
num.length() - den.length() - (if dstr_lt(num, den) { 1 } else { 0 }) + 2
} else {
// adj == -1: 0.1 <= x < 1
let num = (pow10(-e) - c).to_string()
num.length() + e - (if dstr_lt(num, "231") { 1 } else { 0 }) - 1
}
}
///|
/// For a positive finite `x = c · 10^e`, return `Some(k)` iff `c` is a
/// power of ten (so `x = 10^(k_c + e)` for some `k_c`). Used by log10
/// to recognise the exact-result cases.
fn power_of_ten_log(x : Decimal) -> Int32? {
if x.coefficient.is_zero() {
return None
}
let n = digit_count(x.coefficient)
if x.coefficient == pow10(n - 1) {
Some(n - 1 + x.exponent)
} else {
None
}
}
///|
/// GDA `power`: `self ^ other`. Integer exponents use square-and-multiply
/// for exactness; non-integer exponents use `exp(other · ln(self))`.
/// Domain rules: power(0, 0) = 1; power(±0, neg) = ±Infinity with
/// `Division_by_zero`; power(neg, non-integer) = NaN.
pub fn Decimal::power(
self : Decimal,
other : Decimal,
ctx : Context,
) -> (Decimal, Flags) {
let ctx = { ..ctx, flags: Flags::new(), }
(self.power_raw(other, ctx), ctx.flags)
}
///|
/// Internal worker for `power`: returns the value, raising into `ctx.flags`.
fn Decimal::power_raw(
self : Decimal,
other : Decimal,
ctx : Context,
) -> Decimal {
match propagate_nan(self, other, ctx) {
Some(d) => return d
None => ()
}
// Special-value combinations follow GDA §5.4.4 closely.
match (self.class, other.class) {
(Infinity, Finite) => power_infinity_finite(self, other, ctx)
(Finite, Infinity) => power_finite_infinity(self, other, ctx)
(Infinity, Infinity) => power_infinity_infinity(self, other, ctx)
(Finite, Finite) => power_finite(self, other, ctx)
_ => abort("Decimal::power: unreachable class combination")
}
}
///|
/// Infinity ^ finite (GDA §monadic power, infinite first operand).
///
/// * `Inf^0 = 1` (including `-Inf^0` and `-Inf^-0`).
/// * A negative base (`-Inf`) raised to a non-integer is `NaN`
/// (`Invalid_operation`) — the result would not be real.
/// * `Inf^negative` → signed `0`; `Inf^positive` → signed `Infinity`. The
/// sign is negative only when the base is negative and the exponent is an
/// odd integer (`-Inf^-1 = -0`, `-Inf^1 = -Infinity`, `-Inf^2 = +Infinity`).
fn power_infinity_finite(x : Decimal, y : Decimal, ctx : Context) -> Decimal {
if y.coefficient.is_zero() {
return Decimal::one()
}
if x.negative && !is_integer(y) {
return invalid_nan(ctx)
}
let neg = x.negative && is_odd_integer(y)
if y.negative {
finite_zero(0, neg)
} else {
signed_infinity(neg)
}
}
///|
/// Finite ^ infinity.
///
/// * `0^(+Inf) = +0`, `0^(-Inf) = +Infinity` — `power` does *not* raise
/// `Division_by_zero` (unlike `divide`).
/// * A negative finite base raised to `±Infinity` is `NaN`
/// (`Invalid_operation`): the sign would oscillate, so the limit is undefined.
/// * `1^(±Inf) = 1` — but returned rounded to precision with `Inexact` /
/// `Rounded` (the infinite exponent makes the result a limit).
/// * Otherwise the result is `+0` or `+Infinity` by whether `|x| > 1` agrees
/// with the exponent's sign.
fn power_finite_infinity(x : Decimal, y : Decimal, ctx : Context) -> Decimal {
if x.coefficient.is_zero() {
return if y.negative { signed_infinity(false) } else { Decimal::zero() }
}
if x.negative {
return invalid_nan(ctx)
}
if is_one_abs(x) {
return power_one_infinity(ctx)
}
let mag_above_one = magnitude_above_one(x)
if mag_above_one == y.negative {
Decimal::zero()
} else {
signed_infinity(false)
}
}
///|
/// `1 ^ ±Infinity`: the value is exactly 1, but it is rounded to the
/// context precision and flags `Inexact` / `Rounded` (the infinite exponent
/// makes the result a limit). With no precision cap it is just `1`.
fn power_one_infinity(ctx : Context) -> Decimal {
if ctx.precision <= 0 {
return Decimal::one()
}
ctx.raise_inexact()
ctx.raise_rounded()
{
class: Finite,
negative: false,
coefficient: pow10(ctx.precision - 1),
exponent: -(ctx.precision - 1),
}
}
///|
/// Infinity ^ Infinity.
fn power_infinity_infinity(x : Decimal, y : Decimal, ctx : Context) -> Decimal {
// A negative base (`-Inf`) raised to `±Infinity` is undefined → NaN.
if x.negative {
return invalid_nan(ctx)
}
// `+Inf^(-Inf) = +0`, `+Inf^(+Inf) = +Infinity`.
if y.negative {
Decimal::zero()
} else {
signed_infinity(false)
}
}
///|
/// Finite ^ finite.
fn power_finite(x : Decimal, y : Decimal, ctx : Context) -> Decimal {
let p = ctx.precision
// GDA: 0^0 is NaN + Invalid_operation (the limit is indeterminate).
if x.coefficient.is_zero() && y.coefficient.is_zero() {
return invalid_nan(ctx)
}
// x^0 = 1 for any finite non-zero x.
if y.coefficient.is_zero() {
return Decimal::one()
}
let y_int = integer_value(y)
let y_is_int = is_integer(y)
// The result is negative only for a negative base raised to an odd integer.
let result_neg = x.negative &&
(match y_int {
Some(n) => n % 2 != 0
None => false
})
// A negative base raised to a non-integer is invalid (the result is complex).
// `(-0)^non-integer` falls through to the zero handling below.
if x.negative && !y_is_int && !x.coefficient.is_zero() {
return invalid_nan(ctx)
}
// From here on work with the magnitude; the sign is `result_neg`.
let ax : Decimal = { ..x, negative: false, }
// power(±0, y≠0): negative y → signed Infinity, positive y → signed zero.
// `power` does not raise Division_by_zero (unlike `divide`).
if ax.coefficient.is_zero() {
return if y.negative {
signed_infinity(result_neg)
} else {
finite_zero(0, result_neg)
}
}
// Integer exponents within the exact path's range (a positive value up
// to 999_999_999, or a negative one down to -1_999_999_997) compute under the
// usual context bounds; any other exponent routes through the ln/exp series,
// which is gated behind the `MAX_MATH` context restriction. Reject an
// over-wide context for those cases up front — this is also what stops
// `power(1, 1.1)` at precision 100_000_000 from evaluating ln to a hundred
// million digits.
let in_int_range = match y_int {
Some(n) => n >= -1_999_999_997 && n <= 999_999_999
None => false
}
if !in_int_range {
// An over-wide context can't bound the working precision → Invalid_context.
if math_context_invalid(ctx) {
ctx.raise_invalid_context()
return Decimal::nan()
}
// An operand whose adjusted exponent or width exceeds MAX_MATH is out of
// the math functions' domain → Invalid_operation.
if operand_out_of_math_range(ax) || operand_out_of_math_range(y) {
return invalid_nan(ctx)
}
}
// `1^y = 1`, but the exponent and flags depend on `y` (GDA §power).
if is_one(ax) {
return power_one(x.exponent, y, y_int, y_is_int, result_neg, ctx)
}
// Crude overflow / underflow screen: with `bound = log10_exp_bound(x) +
// adjusted(y)`, the result's order of magnitude is around `10^bound`, so a
// large `bound` means the value overflows e_max or underflows past etiny.
// This both shortcuts extreme inputs and, crucially, propagates the
// Overflow / Underflow flags that an internal working context would swallow.
let etiny = ctx.etiny()
let bound = log10_exp_bound(ax) + adjusted_exponent(y)
let overflowing = (adjusted_exponent(ax) >= 0) == !y.negative
if overflowing {
if bound >= int_digits(ctx.e_max) {
return (
{
class: Finite,
negative: result_neg,
coefficient: 1N,
exponent: ctx.e_max + 1,
} : Decimal).finalize_raw(ctx)
}
} else if bound >= int_digits(-etiny) {
return (
{
class: Finite,
negative: result_neg,
coefficient: 1N,
exponent: etiny - 1,
} : Decimal).finalize_raw(ctx)
}
// In-range integer exponent → exact square-and-multiply (sign handled by the
// repeated multiply, matching `result_neg`).
match y_int {
Some(n) =>
if in_int_range {
let r = power_int(x, n, ctx)
// `power_int` evaluates in a wide internal context, so it returns the
// right *value* but the caller's Overflow / Underflow signals were
// absorbed there. A finite non-zero base to a finite power can only
// land on Infinity by overflowing e_max or on zero by underflowing
// past etiny, so re-raise exactly those signals here (the squaring runs
// in a wide internal context that absorbed them).
if r.class is Infinity {
ctx.raise_overflow()
ctx.raise_inexact()
ctx.raise_rounded()
} else if r.coefficient.is_zero() {
ctx.raise_underflow()
ctx.raise_subnormal()
ctx.raise_inexact()
ctx.raise_rounded()
}
return r
}
None => ()
}
// General case: correctly-rounded `x^y` via the `dpower` kernel in a Ziv loop
// that widens precision until the result rounds unambiguously. `power`
// respects the context rounding mode (unlike exp / ln / log10).
let yc = if y.negative { -y.coefficient } else { y.coefficient }
let (coeff, exp) = for extra = 3 {
let (coeff, exp) = dpower(
ax.coefficient,
ax.exponent,
yc,
y.exponent,
p + extra,
)
if ziv_roundable(coeff, p) {
break (coeff, exp)
} else {
continue extra + 3
}
}
(
{ class: Finite, negative: result_neg, coefficient: coeff, exponent: exp, } :
Decimal).finalize_raw(ctx)
}
///|
/// `1^y`: the value is always 1, but GDA fixes the exponent (and the flags)
/// from `y`. For an integer `y` the ideal exponent is `self.exp * int(y)`
/// (clamped at `1 - precision`, raising `Rounded` if it clamps); for a
/// non-integer `y` the result is `1.000…0` at `1 - precision` with `Inexact`
/// and `Rounded`.
fn power_one(
self_exp : Int32,
y : Decimal,
y_int : Int32?,
y_is_int : Bool,
result_neg : Bool,
ctx : Context,
) -> Decimal {
let p = ctx.precision
let exp = if y_is_int {
let multiplier = if y.negative {
0
} else {
match y_int {
Some(n) => if n > p { p } else { n }
None => p // huge positive integer: clamp the multiplier to precision
}
}
let e = self_exp * multiplier
if e < 1 - p {
ctx.raise_rounded()
1 - p
} else {
e
}
} else {
ctx.raise_inexact()
ctx.raise_rounded()
1 - p
}
// value 1 = 10^(-exp) * 10^exp, rendered with -exp trailing zeros.
{
class: Finite,
negative: result_neg,
coefficient: pow10(-exp),
exponent: exp,
}
}
///|
/// Integer-power via square-and-multiply, with negative exponents
/// expressed as `1 / power(x, |n|)`.
fn power_int(x : Decimal, n : Int32, ctx : Context) -> Decimal {
if n == 0 {
return Decimal::one()
}
// Wide exponent range so an intermediate (e.g. `base^|n|` for a negative
// exponent) stays finite and the reciprocal can underflow to a representable
// subnormal rather than spuriously hitting 0. The bound is kept below
// `Int.max / 2` so summing two in-range exponents never overflows `Int`;
// genuinely overflowing results trip it and become ±Infinity, which the
// caller turns into the right signals.
let workctx = Context::new(
precision=ctx.precision + 10,
rounding=HalfEven,
e_max=1_050_000_000,
e_min=-1_050_000_000,
)
let mut base = x
let mut result = Decimal::one()
let mut exp = if n < 0 { -n } else { n }
while exp > 0 {
if exp % 2 == 1 {
result = Decimal::multiply_raw(result, base, workctx)
}
exp = exp / 2
if exp > 0 {
base = Decimal::multiply_raw(base, base, workctx)
}
}
if n < 0 {
result = Decimal::divide_raw(Decimal::one(), result, workctx)
}
result.finalize_raw(ctx)
}
///|
/// Return `Some(n)` iff `y` is exactly representable as an `Int` —
/// non-negative or negative integer with no fractional part.
fn integer_value(y : Decimal) -> Int32? {
if !(y.class is Finite) {
return None
}
if y.exponent >= 0 {
bigint_to_int(y.coefficient * pow10(y.exponent), y.negative)
} else if y.coefficient.is_zero() {
Some(0)
} else if -y.exponent >= digit_count(y.coefficient) {
// More fractional places than the coefficient has digits ⇒ it cannot be
// divisible by 10^(-exp), so the value is fractional. Checking this first
// avoids building a huge `pow10` for a tiny operand like `1E-999999999`.
None
} else {
// Integer iff the coefficient is divisible by 10^(-exp).
let factor = pow10(-y.exponent)
if (y.coefficient % factor).is_zero() {
bigint_to_int(y.coefficient / factor, y.negative)
} else {
None
}
}
}
///|
/// True iff `y` is an integer (no fractional part), for any magnitude.
/// Unlike `integer_value` this never overflows — it only asks the
/// yes/no question, used by `power(-Inf, y)` to reject non-integer
/// exponents on a negative base.
fn is_integer(y : Decimal) -> Bool {
if !(y.class is Finite) {
return false
}
if y.exponent >= 0 {
return true
}
if y.coefficient.is_zero() {
return true
}
// See `integer_value`: more fractional places than digits ⇒ not an integer
// (and avoids a huge `pow10`).
if -y.exponent >= digit_count(y.coefficient) {
return false
}
(y.coefficient % pow10(-y.exponent)).is_zero()
}
///|
/// True iff `y` is an odd integer. Used by `power(Inf, y)` to decide
/// whether the result inherits `Inf`'s sign.
fn is_odd_integer(y : Decimal) -> Bool {
match integer_value(y) {
Some(n) => n % 2 != 0
None => false
}
}
///|
/// True iff `|x| == 1` (any representation).
fn is_one_abs(x : Decimal) -> Bool {
is_one({ ..x, negative: false, })
}
///|
/// True iff `|x| > 1` for finite non-zero x.
fn magnitude_above_one(x : Decimal) -> Bool {
let adj = adjusted_exponent(x)
if adj > 0 {
return true
}
if adj < 0 {
return false
}
// adj == 0: 1.xxx; magnitude > 1 iff coefficient > 10^(digits-1).
let n = digit_count(x.coefficient)
x.coefficient > pow10(n - 1)
}