jsonschema_value/

numeric.rs

#![allow(
    clippy::cast_possible_truncation,
    clippy::cast_possible_wrap,
    clippy::cast_sign_loss,
    clippy::cast_precision_loss,
    clippy::float_cmp,
    clippy::must_use_candidate
)]

use fraction::{BigFraction, One, Zero};
#[cfg(feature = "arbitrary-precision")]
use std::cmp::Ordering;

/// Exact ordering of `value` against `limit`, given `rounded`, the instance's `f64` form.
///
/// Rounding to `f64` is monotone, so an instance landing strictly to one side of the limit is on
/// that side exactly. Disagreement needs a conversion that saturates, underflows to a signed
/// zero, or lands on the limit itself, and only those take the exact route.
/// `None` leaves the caller on `f64`.
#[cfg(feature = "arbitrary-precision")]
#[inline]
fn exact_ordering<N, T>(value: &N, rounded: f64, limit: T) -> Option<Ordering>
where
    N: crate::JsonNumber,
    T: Copy + num_traits::ToPrimitive,
    f64: num_cmp::NumCmp<T>,
{
    let saturated = rounded <= i64::MIN as f64 || rounded >= u64::MAX as f64;
    if !saturated && !num_cmp::NumCmp::num_eq(rounded, limit) {
        return None;
    }
    bignum::compare_to_limit(&value.to_number(), limit)
}

macro_rules! define_num_cmp {
    ($($trait_fn:ident => $fn_name:ident, $op:tt, $infinity_positive:literal, $ord_pat:pat),* $(,)?) => {
        $(
            pub fn $fn_name<N, T>(value: &N, limit: T) -> bool
            where
                N: crate::JsonNumber,
                T: Copy + num_traits::ToPrimitive,
                u64: num_cmp::NumCmp<T>,
                i64: num_cmp::NumCmp<T>,
                f64: num_cmp::NumCmp<T>,
            {
                if let Some(v) = value.as_u64() {
                    num_cmp::NumCmp::$trait_fn(v, limit)
                } else if let Some(v) = value.as_i64() {
                    num_cmp::NumCmp::$trait_fn(v, limit)
                } else if let Some(v) = value.as_f64() {
                    #[cfg(feature = "arbitrary-precision")]
                    if let Some(ordering) = exact_ordering(value, v, limit) {
                        return matches!(ordering, $ord_pat);
                    }
                    num_cmp::NumCmp::$trait_fn(v, limit)
                } else {
                    #[cfg(feature = "arbitrary-precision")]
                    if let Some(big_value) = bignum::try_parse_bigfraction(&value.to_number()) {
                        if let Some(limit_f64) = num_traits::ToPrimitive::to_f64(&limit) {
                            let limit_frac = BigFraction::from(limit_f64);
                            return big_value $op limit_frac;
                        }
                    }
                    // Past `f64` with nothing to place it exactly: an infinity of its own sign.
                    let is_negative = value.as_str().starts_with('-');
                    if $infinity_positive {
                        !is_negative
                    } else {
                        is_negative
                    }
                }
            }
        )*
    };
}

define_num_cmp!(
    num_ge => ge, >=, true, Ordering::Greater | Ordering::Equal,   // +infinity passes >=, >
    num_le => le, <=, false, Ordering::Less | Ordering::Equal,  // -infinity passes <=, <
    num_gt => gt, >, true, Ordering::Greater,
    num_lt => lt, <, false, Ordering::Less,
);

#[cfg(feature = "macros")]
pub fn eq<N, T>(value: &N, limit: T) -> bool
where
    N: crate::JsonNumber,
    T: Copy + num_traits::ToPrimitive,
    u64: num_cmp::NumCmp<T>,
    i64: num_cmp::NumCmp<T>,
    f64: num_cmp::NumCmp<T>,
{
    if let Some(v) = value.as_u64() {
        num_cmp::NumCmp::num_eq(v, limit)
    } else if let Some(v) = value.as_i64() {
        num_cmp::NumCmp::num_eq(v, limit)
    } else if let Some(v) = value.as_f64() {
        #[cfg(feature = "arbitrary-precision")]
        if let Some(ordering) = exact_ordering(value, v, limit) {
            return ordering == Ordering::Equal;
        }
        num_cmp::NumCmp::num_eq(v, limit)
    } else {
        #[cfg(feature = "arbitrary-precision")]
        if let Some(big_value) = bignum::try_parse_bigfraction(&value.to_number()) {
            if let Some(limit_f64) = num_traits::ToPrimitive::to_f64(&limit) {
                return big_value == BigFraction::from(limit_f64);
            }
        }
        false
    }
}

/// A finite `f64` as the decimal it prints as: `mantissa / 10^decimals`.
///
/// `0.1` reads as `1/10`, the decimal JSON Schema means, not the binary `f64` holds.
/// `None` for anything outside `i128`, which leaves the caller on the fraction path.
fn decimal_parts(value: f64) -> Option<(i128, i32)> {
    if !value.is_finite() {
        return None;
    }
    let mut buffer = zmij::Buffer::new();
    let mut mantissa: i128 = 0;
    let mut decimals = 0;
    let mut exponent = 0;
    let mut negative = false;
    let mut fractional = false;
    let mut bytes = buffer.format_finite(value).bytes();
    for byte in &mut bytes {
        match byte {
            b'-' => negative = true,
            b'.' => fractional = true,
            // `zmij` writes an exponent for magnitudes far from one, as in `1e+300`.
            b'e' => {
                exponent = parse_exponent(&mut bytes)?;
                break;
            }
            _ => {
                mantissa = mantissa
                    .checked_mul(10)?
                    .checked_add(i128::from(byte.checked_sub(b'0')?))?;
                decimals += i32::from(fractional);
            }
        }
    }
    Some((
        if negative { -mantissa } else { mantissa },
        decimals - exponent,
    ))
}

/// The signed exponent left in `bytes` after an `e`.
fn parse_exponent(bytes: &mut impl Iterator<Item = u8>) -> Option<i32> {
    let mut exponent = 0_i32;
    let mut negative = false;
    for byte in bytes {
        match byte {
            b'+' => {}
            b'-' => negative = true,
            _ => {
                exponent = exponent
                    .checked_mul(10)?
                    .checked_add(i32::from(byte.checked_sub(b'0')?))?;
            }
        }
    }
    Some(if negative { -exponent } else { exponent })
}

/// Whether `value / multiple` is an integer, in the decimal reading both operands print as.
///
/// `None` when either side leaves `i128`, which leaves the caller on `BigFraction`. That
/// fallback is not exact - `fraction` builds its rational from around 16 significant digits
/// of the binary value, reading `1070468.14` as `1070468.1399999998` - so this answers
/// wherever it can rather than only where the two agree.
fn divides_exactly(value: f64, multiple: f64) -> Option<bool> {
    let (value_mantissa, value_decimals) = decimal_parts(value)?;
    let (multiple_mantissa, multiple_decimals) = decimal_parts(multiple)?;
    if multiple_mantissa == 0 {
        return None;
    }
    // value / multiple = (value_mantissa * 10^multiple_decimals)
    //                  / (multiple_mantissa * 10^value_decimals)
    // Cancelling the shared powers of ten first keeps both sides inside `i128` far more often.
    let shared = value_decimals.min(multiple_decimals);
    let scale = |mantissa: i128, decimals: i32| {
        let places = u32::try_from(decimals - shared).ok()?;
        mantissa.checked_mul(10_i128.checked_pow(places)?)
    };
    Some(scale(value_mantissa, multiple_decimals)? % scale(multiple_mantissa, value_decimals)? == 0)
}

pub fn is_multiple_of_float<N: crate::JsonNumber>(value: &N, multiple: f64) -> bool {
    #[cfg(feature = "arbitrary-precision")]
    if let Some(decimal) = bignum::past_digit_budget(&value.as_str()) {
        return bignum::Decimal::of_limit(multiple)
            .is_some_and(|multiple| decimal.is_multiple_of(&multiple));
    }
    if let Some(value_f64) = value.as_f64() {
        // Zero is a multiple of any non-zero number, but a magnitude below the smallest
        // subnormal reads as zero without being one.
        if value_f64.is_zero() {
            return decimal_is_zero(&value.as_str());
        }
        if value_f64.abs() < multiple {
            return false;
        }
        // From the JSON Schema spec
        //
        // > A numeric instance is valid only if division by this keyword's value results in an integer.
        //
        // For fractions, integers have denominator equal to one.
        //
        // Ref: https://json-schema.org/draft/2020-12/json-schema-validation#section-6.2.1
        if let Some(answer) = divides_exactly(value_f64, multiple) {
            return answer;
        }
        (BigFraction::from(value_f64) / BigFraction::from(multiple))
            .denom()
            .is_none_or(One::is_one)
    } else {
        // This branch is only possible for large floats in scientific notation, we don't really
        // support it
        false
    }
}

/// The maximum integer that can be exactly represented in f64.
/// Beyond this value, f64 loses precision and arithmetic operations become unreliable.
const MAX_SAFE_INTEGER: u64 = 1u64 << 53;

/// Whether the number written in `text` is exactly zero: `0e5` is, `1e-400` is not.
fn decimal_is_zero(text: &str) -> bool {
    let mantissa = text.split(['e', 'E']).next().unwrap_or(text);
    mantissa
        .bytes()
        .all(|byte| !byte.is_ascii_digit() || byte == b'0')
}

/// Whether the plain decimal integer in `text` divides by `divisor`, by long division over its
/// digits; exact at any width. `None` for anything else.
#[cfg(not(feature = "arbitrary-precision"))]
pub(crate) fn decimal_is_multiple_of(text: &str, divisor: u64) -> Option<bool> {
    if text.contains(['e', 'E']) {
        return None;
    }
    let text = text.strip_prefix('-').unwrap_or(text);
    let (digits, fraction) = match text.split_once('.') {
        Some((digits, fraction)) => (digits, Some(fraction)),
        None => (text, None),
    };
    // A fraction of nothing but zeros leaves the value whole.
    if fraction.is_some_and(|fraction| !fraction.bytes().all(|byte| byte == b'0')) {
        return Some(false);
    }
    // `remainder` stays below `divisor`, at most 2^53, so the step cannot overflow.
    let mut remainder = 0_u64;
    for byte in digits.bytes() {
        remainder = (remainder * 10 + u64::from(byte - b'0')) % divisor;
    }
    Some(remainder == 0)
}

pub fn is_multiple_of_integer<N: crate::JsonNumber>(value: &N, multiple: f64) -> bool {
    // Integer instances use integer modulo directly: it is exact and avoids the slower float
    // `fract()` + `%`. The divisor guard keeps it exact - divisors above 2^53 may already have
    // lost precision when converted to f64 during schema compilation, and `multiple > 0.0` avoids
    // a divide-by-zero panic on the integer modulo. Non-integer or huge instances fall through to
    // the f64 path below.
    let divisor_ok =
        multiple > 0.0 && multiple <= MAX_SAFE_INTEGER as f64 && multiple.fract() == 0.0;
    if divisor_ok {
        if let Some(v) = value.as_u64() {
            return (v % (multiple as u64)) == 0;
        }
        if let Some(v) = value.as_i64() {
            return (v % (multiple as i64)) == 0;
        }
        // An integer past `u64` still divides exactly, and `as_f64` below would answer about the
        // value it rounds to instead.
        #[cfg(feature = "arbitrary-precision")]
        if let Some(decimal) = bignum::past_digit_budget(&value.as_str()) {
            return bignum::Decimal::of_limit(multiple)
                .is_some_and(|multiple| decimal.is_multiple_of(&multiple));
        }
        #[cfg(feature = "arbitrary-precision")]
        if let Some(big_value) = bignum::try_parse_bigint(&value.to_number()) {
            let divisor = num_bigint::BigInt::from(multiple as i64);
            return bignum::is_multiple_of_bigint(&big_value, &divisor);
        }
        // Only where `f64` cannot answer exactly, so the literal is not rendered on the hot path.
        #[cfg(not(feature = "arbitrary-precision"))]
        if value
            .as_f64()
            .is_none_or(|value_f64| value_f64.abs() >= MAX_SAFE_INTEGER as f64)
        {
            if let Some(answer) = decimal_is_multiple_of(&value.as_str(), multiple as u64) {
                return answer;
            }
        }
    }

    if let Some(value_f64) = value.as_f64() {
        // A magnitude below the smallest subnormal underflows to zero, which the modulo below
        // would read as the divisor dividing evenly; such a value is a proper fraction of any
        // whole divisor.
        if value_f64 == 0.0 && !decimal_is_zero(&value.as_str()) {
            return false;
        }
        // As the divisor has its fractional part as zero, then any value with a non-zero
        // fractional part can't be a multiple of this divisor, therefore it is short-circuited
        value_f64.fract() == 0. && (value_f64 % multiple) == 0.
    } else {
        // Number doesn't fit in f64 - must be huge with arbitrary_precision
        #[cfg(feature = "arbitrary-precision")]
        {
            // Try parsing as BigInt first for large integers
            if let Some(big_value) = bignum::try_parse_bigint(&value.to_number()) {
                use num_bigint::BigInt;
                // Convert the multiple to BigInt.
                // Note: For large divisors beyond i64/u64 range, the schema compilation
                // should have created a MultipleOfBigIntValidator instead, which stores
                // the divisor as BigInt directly. This path handles the case where the
                // instance is huge but the divisor fits in f64.
                // Since we know multiple is an integer (checked before calling this function),
                // we can safely convert via i64 for divisors in the i64 range.
                // For divisors beyond i64 but representable in f64, precision may be lost,
                // but that's inherent to f64 representation.
                let multiple_int = BigInt::from(multiple as i64);
                return bignum::is_multiple_of_bigint(&big_value, &multiple_int);
            }
            // Not an integer - can't be a multiple of an integer divisor
            false
        }
        // Exponent forms past `f64` are placed only by `arbitrary-precision`.
        #[cfg(not(feature = "arbitrary-precision"))]
        {
            false
        }
    }
}

#[cfg(feature = "arbitrary-precision")]
pub mod bignum {
    use fraction::BigFraction;
    use num_bigint::BigInt;
    use num_traits::{ToPrimitive, Zero};
    use serde_json::Number;
    use std::str::FromStr;

    /// The most digits `BigInt` and `BigFraction` materialise for one number. Their arithmetic
    /// grows quadratically with the digit count and a short literal like `1e-1000000` writes a
    /// million, so numbers past this budget take [`Decimal`], which is linear in the written text.
    const MAX_DIGITS: u64 = 10_000;

    /// Whether materialising the number written in `text` takes more than `MAX_DIGITS` digits:
    /// the digits it writes plus the zeros its exponent shifts in.
    #[inline]
    pub fn exceeds_digit_budget(text: &str) -> bool {
        exceeds_digit_budget_with(text, has_exponent(text))
    }

    fn has_exponent(text: &str) -> bool {
        memchr::memchr2(b'e', b'E', text.as_bytes()).is_some()
    }

    fn exceeds_digit_budget_with(text: &str, has_exponent: bool) -> bool {
        // Without an exponent the text is at least as long as the digits it materialises.
        if !has_exponent {
            return text.len() as u64 > MAX_DIGITS;
        }
        let mut digits: u64 = 0;
        let mut fraction: i64 = 0;
        let mut in_fraction = false;
        let mut exponent: i64 = 0;
        let mut exponent_negative = false;
        let mut in_exponent = false;
        for byte in text.bytes() {
            match byte {
                b'0'..=b'9' if in_exponent => {
                    exponent = exponent
                        .saturating_mul(10)
                        .saturating_add(i64::from(byte - b'0'));
                }
                b'0'..=b'9' => {
                    digits += 1;
                    fraction += i64::from(in_fraction);
                }
                b'.' => in_fraction = true,
                b'e' | b'E' => in_exponent = true,
                b'-' if in_exponent => exponent_negative = true,
                _ => {}
            }
        }
        let exponent = if exponent_negative {
            -exponent
        } else {
            exponent
        };
        digits.saturating_add(exponent.saturating_sub(fraction).unsigned_abs()) > MAX_DIGITS
    }

    /// The number written in `text` as a [`Decimal`] when it [`exceeds_digit_budget`].
    pub fn past_digit_budget(text: &str) -> Option<Decimal> {
        exceeds_digit_budget(text).then(|| Decimal::parse(text))
    }

    /// A decimal number, `digits * 10^exponent`, with no leading or trailing zeros in `digits`;
    /// zero has no digits. Exact at any magnitude, with work linear in the written text.
    #[derive(Debug, Clone, PartialEq, Eq)]
    pub struct Decimal {
        negative: bool,
        digits: Vec<u8>,
        exponent: i64,
    }

    impl Decimal {
        /// The number written in `text`, a JSON number literal.
        // ponytail: exponents saturate at `i64`, so numbers written past `1e9223372036854775807`
        // compare equal to each other.
        pub fn parse(text: &str) -> Self {
            let mut negative = false;
            let mut digits = Vec::new();
            let mut fraction: i64 = 0;
            let mut in_fraction = false;
            let mut exponent: i64 = 0;
            let mut exponent_negative = false;
            let mut in_exponent = false;
            for byte in text.bytes() {
                match byte {
                    b'0'..=b'9' if in_exponent => {
                        exponent = exponent
                            .saturating_mul(10)
                            .saturating_add(i64::from(byte - b'0'));
                    }
                    b'0'..=b'9' => {
                        if !(digits.is_empty() && byte == b'0') {
                            digits.push(byte);
                        }
                        fraction += i64::from(in_fraction);
                    }
                    b'.' => in_fraction = true,
                    b'e' | b'E' => in_exponent = true,
                    b'-' if in_exponent => exponent_negative = true,
                    b'-' => negative = true,
                    _ => {}
                }
            }
            let trailing = digits
                .iter()
                .rev()
                .take_while(|&&byte| byte == b'0')
                .count();
            digits.truncate(digits.len() - trailing);
            if digits.is_empty() {
                return Self {
                    negative: false,
                    digits,
                    exponent: 0,
                };
            }
            let exponent = if exponent_negative {
                -exponent
            } else {
                exponent
            };
            Self {
                negative,
                digits,
                exponent: exponent
                    .saturating_sub(fraction)
                    .saturating_add(trailing as i64),
            }
        }

        /// A primitive limit as the decimal it prints as; `None` for infinities and NaN.
        pub fn of_limit<T: Copy + ToPrimitive>(limit: T) -> Option<Self> {
            let float = limit.to_f64()?;
            if float.fract() == 0.0 {
                if let Some(integer) = limit.to_i64() {
                    return Some(Self::parse(&integer.to_string()));
                }
                if let Some(integer) = limit.to_u64() {
                    return Some(Self::parse(&integer.to_string()));
                }
            }
            float
                .is_finite()
                .then(|| Self::parse(zmij::Buffer::new().format_finite(float)))
        }

        pub fn of_integer(value: &BigInt) -> Self {
            Self::parse(&value.to_string())
        }

        /// `None` when no finite decimal writes `value`.
        pub fn of_fraction(value: &BigFraction) -> Option<Self> {
            use num_bigint::BigUint;
            use num_traits::One;

            let (numerator, denominator) = (value.numer()?, value.denom()?);
            // Scaling by ten clears one factor of two and one of five, so a finite decimal exists
            // exactly when those are the denominator's only prime factors.
            let twos = denominator.trailing_zeros().unwrap_or(0);
            let mut rest = denominator >> twos;
            let five = BigUint::from(5_u8);
            let mut fives = 0_u64;
            while (&rest % &five).is_zero() {
                rest /= &five;
                fives += 1;
            }
            if !rest.is_one() {
                return None;
            }
            let places = twos.max(fives);
            let digits = numerator
                * BigUint::from(2_u8).pow(u32::try_from(places - twos).ok()?)
                * five.pow(u32::try_from(places - fives).ok()?);
            let sign = if value.is_sign_negative() { "-" } else { "" };
            Some(Self::parse(&format!("{sign}{digits}e-{places}")))
        }

        pub fn is_integer(&self) -> bool {
            self.exponent >= 0
        }

        pub fn is_multiple_of(&self, multiple: &Self) -> bool {
            use num_bigint::BigUint;

            if self.digits.is_empty() {
                return true;
            }
            if multiple.digits.is_empty() {
                return false;
            }
            // `self / multiple` is `self.digits / (multiple.digits * 10^-shift)`. A negative shift
            // asks for `self.digits` to divide by ten, which a value with no trailing zero never does.
            let Ok(shift) =
                u64::try_from(i128::from(self.exponent) - i128::from(multiple.exponent))
            else {
                return false;
            };
            let divisor = digit_chunks(&multiple.digits)
                .fold(BigUint::zero(), |value, (scale, chunk)| {
                    value * scale + chunk
                });
            let remainder = digit_chunks(&self.digits)
                .fold(BigUint::zero(), |value, (scale, chunk)| {
                    (value * scale + chunk) % &divisor
                });
            let scale = BigUint::from(10_u8).modpow(&BigUint::from(shift), &divisor);
            (remainder * scale % &divisor).is_zero()
        }
    }

    /// `digits` in chunks of 19, each within `u64`, paired with the power of ten it shifts by.
    fn digit_chunks(digits: &[u8]) -> impl Iterator<Item = (num_bigint::BigUint, u64)> + '_ {
        digits.chunks(19).map(|chunk| {
            let value = chunk
                .iter()
                .fold(0_u64, |value, byte| value * 10 + u64::from(byte - b'0'));
            (
                num_bigint::BigUint::from(10_u64.pow(chunk.len() as u32)),
                value,
            )
        })
    }

    impl PartialOrd for Decimal {
        fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
            Some(self.cmp(other))
        }
    }

    impl Ord for Decimal {
        fn cmp(&self, other: &Self) -> std::cmp::Ordering {
            let sign = |value: &Self| match (value.digits.is_empty(), value.negative) {
                (true, _) => 0,
                (false, true) => -1,
                (false, false) => 1,
            };
            // The position of the leading digit orders magnitudes first; with no trailing zeros,
            // digit strings sharing that position order lexicographically.
            let leading = |value: &Self| value.digits.len() as i128 + i128::from(value.exponent);
            sign(self).cmp(&sign(other)).then_with(|| {
                let magnitude = leading(self)
                    .cmp(&leading(other))
                    .then_with(|| self.digits.cmp(&other.digits));
                if self.negative {
                    magnitude.reverse()
                } else {
                    magnitude
                }
            })
        }
    }

    #[derive(Debug, Clone)]
    struct DecimalComponents {
        negative: bool,
        digits: String,
        fraction_digits: usize,
        exponent: i64,
    }

    impl DecimalComponents {
        fn parse(num_str: &str) -> Option<Self> {
            let bytes = num_str.as_bytes();
            if bytes.is_empty() {
                return None;
            }

            let mut idx = 0;
            let negative = if bytes[idx] == b'-' {
                idx += 1;
                true
            } else {
                false
            };

            if idx >= bytes.len() {
                return None;
            }

            let mut digits = String::with_capacity(bytes.len());
            let int_start = idx;
            while idx < bytes.len() && bytes[idx].is_ascii_digit() {
                idx += 1;
            }
            if int_start == idx {
                return None;
            }
            digits.push_str(&num_str[int_start..idx]);

            let mut fraction_digits = 0usize;
            if idx < bytes.len() && bytes[idx] == b'.' {
                idx += 1;
                let frac_start = idx;
                while idx < bytes.len() && bytes[idx].is_ascii_digit() {
                    idx += 1;
                }
                if frac_start == idx {
                    return None;
                }
                digits.push_str(&num_str[frac_start..idx]);
                fraction_digits = idx - frac_start;
            }

            let mut exponent: i64 = 0;
            if idx < bytes.len() && (bytes[idx] == b'e' || bytes[idx] == b'E') {
                idx += 1;
                if idx >= bytes.len() {
                    return None;
                }
                let mut exp_sign: i64 = 1;
                if bytes[idx] == b'+' {
                    idx += 1;
                } else if bytes[idx] == b'-' {
                    exp_sign = -1;
                    idx += 1;
                }
                let exp_start = idx;
                while idx < bytes.len() && bytes[idx].is_ascii_digit() {
                    idx += 1;
                }
                if exp_start == idx {
                    return None;
                }
                let exp_value = num_str[exp_start..idx].parse::<i64>().ok()?;
                exponent = exp_value.checked_mul(exp_sign)?;
            }

            if idx != bytes.len() {
                return None;
            }

            Some(Self {
                negative,
                digits,
                fraction_digits,
                exponent,
            })
        }

        #[inline]
        fn decimal_shift(&self) -> i64 {
            self.exponent - self.fraction_digits as i64
        }
    }

    fn digits_are_zero(s: &str) -> bool {
        s.bytes().all(|b| b == b'0')
    }

    fn trailing_zero_count(s: &str) -> usize {
        s.as_bytes()
            .iter()
            .rev()
            .take_while(|b| **b == b'0')
            .count()
    }

    fn append_zeros(target: &mut String, count: usize) -> Option<()> {
        let new_len = target.len().checked_add(count)?;
        target.reserve(count);
        target.extend(std::iter::repeat_n('0', count));
        debug_assert_eq!(target.len(), new_len);
        Some(())
    }

    fn pow10_bigint(exp: usize) -> Option<BigInt> {
        if exp == 0 {
            return Some(BigInt::from(1));
        }
        let exp_u32 = u32::try_from(exp).ok()?;
        Some(BigInt::from(10).pow(exp_u32))
    }

    /// The rational a whole number denotes. `BigFraction::from` writes the integer out in decimal
    /// and reads it back one digit at a time, while a magnitude over one is already the reduced form.
    pub fn whole(value: BigInt) -> BigFraction {
        let (sign, magnitude) = value.into_parts();
        let fraction = BigFraction::new_raw(magnitude, num_bigint::BigUint::from(1_u8));
        if sign == num_bigint::Sign::Minus {
            -fraction
        } else {
            fraction
        }
    }

    /// Try to parse a Number as `BigInt` if it's outside i64 range or for compile-time
    /// schema values that need exact representation
    pub fn try_parse_bigint(num: &Number) -> Option<BigInt> {
        use super::MAX_SAFE_INTEGER;

        let num_str = num.as_str();

        // Parse as BigInt if it's beyond 2^53 (where f64 loses precision).
        // Values beyond 2^53 need BigInt for accurate arithmetic even if they fit in i64/u64.
        // Note: If as_i64() fails but as_u64() succeeds, the value is in [2^63, 2^64-1],
        // which is always > 2^53, so no additional check needed for u64.
        if let Some(v) = num.as_i64() {
            if v.unsigned_abs() <= MAX_SAFE_INTEGER {
                return None;
            }
        }

        let has_exponent = has_exponent(num_str);
        if exceeds_digit_budget_with(num_str, has_exponent) {
            return None;
        }

        if !has_exponent && !num_str.as_bytes().contains(&b'.') {
            return BigInt::from_str(num_str).ok();
        }

        let mut components = DecimalComponents::parse(num_str)?;
        let mut shift = components.decimal_shift();

        if shift < 0 {
            let needed = (-shift) as usize;
            if digits_are_zero(&components.digits) {
                components.digits.clear();
                components.digits.push('0');
                shift = 0;
            } else {
                let zeros = trailing_zero_count(&components.digits);
                if zeros < needed {
                    return None;
                }
                let new_len = components.digits.len() - needed;
                components.digits.truncate(new_len);
                shift = 0;
            }
        }

        if shift > 0 {
            append_zeros(&mut components.digits, shift as usize)?;
        }

        let digits_trimmed = components.digits.trim_start_matches('0');
        let digits_ref = if digits_trimmed.is_empty() {
            "0"
        } else {
            digits_trimmed
        };
        let mut value = BigInt::from_str(digits_ref).ok()?;
        if components.negative && !value.is_zero() {
            value = -value;
        }
        Some(value)
    }

    /// Try to parse a Number as `BigFraction` for arbitrary precision decimal support
    ///
    /// Returns Some for numbers requiring exact decimal precision:
    /// - Decimals with a decimal point (e.g., `0.1`, `123.456`)
    /// - Scientific notation decimals that can't be represented exactly as f64
    ///
    /// Returns None for:
    /// - Integers that fit in i64 (handled by standard numeric path)
    /// - Large integers including u64 beyond `i64::MAX` (handled by `try_parse_bigint`)
    pub fn try_parse_bigfraction(num: &Number) -> Option<BigFraction> {
        // Skip integers that fit in i64 - they don't need BigFraction
        if num.as_i64().is_some() {
            return None;
        }

        let num_str = num.as_str();

        let has_exponent = has_exponent(num_str);
        if !has_exponent && !num_str.as_bytes().contains(&b'.') {
            return None;
        }

        if exceeds_digit_budget_with(num_str, has_exponent) {
            return None;
        }

        if !has_exponent {
            return BigFraction::from_str(num_str).ok();
        }

        let components = DecimalComponents::parse(num_str)?;
        let shift = components.decimal_shift();

        // A number with exponent that still resolves to an integer is handled by BigInt.
        if shift >= 0 {
            return None;
        }

        let denom_power = (-shift) as usize;
        let denominator = pow10_bigint(denom_power)?;
        let mut numerator = BigInt::from_str(&components.digits).ok()?;
        if components.negative && !numerator.is_zero() {
            numerator = -numerator;
        }
        Some(whole(numerator) / whole(denominator))
    }

    /// Exact ordering of a big-integer instance against a numeric limit.
    ///
    /// Integer-representable limits compare via `BigInt`; infinite limits (schema numbers
    /// beyond the exponent cap) order every finite instance. `None` means the limit has no
    /// exact integer form and the caller should fall back to `f64` comparison.
    pub(crate) fn compare_bigint_to_limit<T>(big: &BigInt, limit: T) -> Option<std::cmp::Ordering>
    where
        T: Copy + ToPrimitive,
    {
        use std::cmp::Ordering;

        let limit_f64 = limit.to_f64()?;
        if limit_f64.fract() == 0.0 {
            // `to_i64`/`to_u64` are exact for u64/i64 limits and for integer-valued f64 limits.
            if let Some(limit_int) = limit.to_i64() {
                return Some(big.cmp(&BigInt::from(limit_int)));
            }
            if let Some(limit_int) = limit.to_u64() {
                return Some(big.cmp(&BigInt::from(limit_int)));
            }
        }
        if limit_f64 == f64::INFINITY {
            return Some(Ordering::Less);
        }
        if limit_f64 == f64::NEG_INFINITY {
            return Some(Ordering::Greater);
        }
        None
    }

    /// The limit as an exact fraction, for instances that only have a rational form.
    ///
    /// `None` where the limit itself is not an exact integer, leaving the caller on `f64`.
    fn limit_as_bigfraction<T>(limit: T) -> Option<BigFraction>
    where
        T: Copy + ToPrimitive,
    {
        if limit.to_f64()?.fract() != 0.0 {
            return None;
        }
        if let Some(limit_int) = limit.to_i64() {
            return Some(BigFraction::from(limit_int));
        }
        limit.to_u64().map(BigFraction::from)
    }

    /// Exact ordering of a JSON number literal against a numeric limit.
    ///
    /// `None` means no exact form is available on one side and the caller should fall back to
    /// `f64` comparison.
    pub(crate) fn compare_to_limit<T>(num: &Number, limit: T) -> Option<std::cmp::Ordering>
    where
        T: Copy + ToPrimitive,
    {
        if let Some(value) = past_digit_budget(num.as_str()) {
            return Some(value.cmp(&Decimal::of_limit(limit)?));
        }
        if let Some(big) = try_parse_bigint(num) {
            return compare_bigint_to_limit(&big, limit);
        }
        let value = try_parse_bigfraction(num)?;
        value.partial_cmp(&limit_as_bigfraction(limit)?)
    }

    macro_rules! define_bigint_cmp {
        ($($fn_name:ident, $prim_type:ty, $to_prim:ident, $op:tt, $overflow_sign:expr);* $(;)?) => {
            $(
                pub fn $fn_name(bigint: &BigInt, value: $prim_type) -> bool {
                    if let Some(converted) = bigint.$to_prim() {
                        converted $op value
                    } else {
                        bigint.sign() == $overflow_sign
                    }
                }
            )*
        };
    }

    define_bigint_cmp!(
        bigint_ge_u64, u64, to_u64, >=, num_bigint::Sign::Plus;
        bigint_le_u64, u64, to_u64, <=, num_bigint::Sign::Minus;
        bigint_gt_u64, u64, to_u64, >, num_bigint::Sign::Plus;
        bigint_lt_u64, u64, to_u64, <, num_bigint::Sign::Minus;
        bigint_ge_i64, i64, to_i64, >=, num_bigint::Sign::Plus;
        bigint_le_i64, i64, to_i64, <=, num_bigint::Sign::Minus;
        bigint_gt_i64, i64, to_i64, >, num_bigint::Sign::Plus;
        bigint_lt_i64, i64, to_i64, <, num_bigint::Sign::Minus;
        bigint_ge_f64, f64, to_f64, >=, num_bigint::Sign::Plus;
        bigint_le_f64, f64, to_f64, <=, num_bigint::Sign::Minus;
        bigint_gt_f64, f64, to_f64, >, num_bigint::Sign::Plus;
        bigint_lt_f64, f64, to_f64, <, num_bigint::Sign::Minus;
    );

    // Generate reverse comparison functions (primitive op BigType -> BigType op primitive)
    macro_rules! define_reverse_cmp {
        ($($rev_ge:ident, $rev_le:ident, $rev_gt:ident, $rev_lt:ident, $prim_type:ty, $big_type:ty, $fwd_ge:ident, $fwd_le:ident, $fwd_gt:ident, $fwd_lt:ident);* $(;)?) => {
            $(
                pub fn $rev_ge(value: $prim_type, big: &$big_type) -> bool {
                    $fwd_le(big, value)
                }

                pub fn $rev_le(value: $prim_type, big: &$big_type) -> bool {
                    $fwd_ge(big, value)
                }

                pub fn $rev_gt(value: $prim_type, big: &$big_type) -> bool {
                    $fwd_lt(big, value)
                }

                pub fn $rev_lt(value: $prim_type, big: &$big_type) -> bool {
                    $fwd_gt(big, value)
                }
            )*
        };
    }

    define_reverse_cmp!(
        u64_ge_bigint, u64_le_bigint, u64_gt_bigint, u64_lt_bigint, u64, BigInt, bigint_ge_u64, bigint_le_u64, bigint_gt_u64, bigint_lt_u64;
        i64_ge_bigint, i64_le_bigint, i64_gt_bigint, i64_lt_bigint, i64, BigInt, bigint_ge_i64, bigint_le_i64, bigint_gt_i64, bigint_lt_i64;
        f64_ge_bigint, f64_le_bigint, f64_gt_bigint, f64_lt_bigint, f64, BigInt, bigint_ge_f64, bigint_le_f64, bigint_gt_f64, bigint_lt_f64;
    );

    /// Check if a Number (as `BigInt`) is a multiple of another `BigInt`
    pub fn is_multiple_of_bigint(value: &BigInt, multiple: &BigInt) -> bool {
        // Zero is a multiple of any non-zero number
        // Mathematically: 0 = k * multiple for k = 0
        if value.is_zero() {
            return true;
        }

        // Note: multiple.is_zero() case is not handled here because JSON Schema
        // validation rejects schemas with "multipleOf: 0" during compilation
        // (exclusiveMinimum constraint requires multipleOf > 0).
        // The modulo operation below would panic if multiple is zero, but this
        // is prevented by schema validation.

        (value % multiple).is_zero()
    }

    // BigFraction comparison functions
    macro_rules! define_bigfraction_cmp {
        ($($fn_name:ident, $prim_type:ty, $op:tt);* $(;)?) => {
            $(
                pub fn $fn_name(bigfrac: &BigFraction, value: $prim_type) -> bool {
                    let value_frac = BigFraction::from(value);
                    *bigfrac $op value_frac
                }
            )*
        };
    }

    define_bigfraction_cmp!(
        bigfrac_ge_u64, u64, >=;
        bigfrac_le_u64, u64, <=;
        bigfrac_gt_u64, u64, >;
        bigfrac_lt_u64, u64, <;
        bigfrac_ge_i64, i64, >=;
        bigfrac_le_i64, i64, <=;
        bigfrac_gt_i64, i64, >;
        bigfrac_lt_i64, i64, <;
        bigfrac_ge_f64, f64, >=;
        bigfrac_le_f64, f64, <=;
        bigfrac_gt_f64, f64, >;
        bigfrac_lt_f64, f64, <;
    );

    define_reverse_cmp!(
        u64_ge_bigfrac, u64_le_bigfrac, u64_gt_bigfrac, u64_lt_bigfrac, u64, BigFraction, bigfrac_ge_u64, bigfrac_le_u64, bigfrac_gt_u64, bigfrac_lt_u64;
        i64_ge_bigfrac, i64_le_bigfrac, i64_gt_bigfrac, i64_lt_bigfrac, i64, BigFraction, bigfrac_ge_i64, bigfrac_le_i64, bigfrac_gt_i64, bigfrac_lt_i64;
        f64_ge_bigfrac, f64_le_bigfrac, f64_gt_bigfrac, f64_lt_bigfrac, f64, BigFraction, bigfrac_ge_f64, bigfrac_le_f64, bigfrac_gt_f64, bigfrac_lt_f64;
    );

    /// Check if a `BigFraction` is a multiple of another value
    pub fn is_multiple_of_bigfrac(value: &BigFraction, multiple: &BigFraction) -> bool {
        // Zero is a multiple of any non-zero number
        if value.is_zero() {
            return true;
        }
        // Division by zero is undefined, so return false
        if multiple.is_zero() {
            return false;
        }
        // A number is a multiple of another if division results in an integer
        // (denominator of the result is 1)
        (value / multiple).denom().is_none_or(fraction::One::is_one)
    }
}

#[cfg(test)]
mod tests {
    use super::{decimal_parts, divides_exactly};
    use test_case::test_case;

    #[test_case(0.1, Some((1, 1)); "leading zero")]
    #[test_case(2.675, Some((2675, 3)); "three decimals")]
    #[test_case(-0.25, Some((-25, 2)); "negative")]
    // `zmij` always writes a fractional part, so an integral value scales by ten.
    #[test_case(7.0, Some((70, 1)); "integral")]
    #[test_case(1e-7, Some((1, 7)); "negative exponent")]
    #[test_case(1e300, Some((1, -300)); "positive exponent")]
    #[test_case(f64::NAN, None; "not a number")]
    #[test_case(f64::INFINITY, None; "infinite")]
    fn decimal_parts_reads_the_printed_decimal(value: f64, expected: Option<(i128, i32)>) {
        assert_eq!(decimal_parts(value), expected);
    }

    // `BigFraction::from(f64)` rounds these into non-multiples; the decimal reading does not.
    #[test_case(1_070_468.14, 0.01, true; "large amount of cents")]
    #[test_case(1_070_468.13, 0.01, true; "another large amount of cents")]
    #[test_case(1_070_468.145, 0.01, false; "large amount of half cents")]
    #[test_case(19.99, 0.01, true; "small amount of cents")]
    #[test_case(0.0075, 0.0001, true; "fourth decimal place")]
    #[test_case(5.35, 2.675, true; "fractional divisor")]
    #[test_case(505_661.899_999_999_97, 0.1, false; "seventeen significant digits")]
    fn divides_exactly_answers(value: f64, multiple: f64, expected: bool) {
        assert_eq!(divides_exactly(value, multiple), Some(expected));
    }

    #[test_case(1e300; "too large to scale into i128")]
    #[test_case(1e-300; "too small to scale into i128")]
    fn divides_exactly_defers_out_of_range(value: f64) {
        assert_eq!(divides_exactly(value, 0.01), None);
    }
}

#[cfg(all(test, feature = "arbitrary-precision"))]
mod bignum_tests {
    use crate::numeric::bignum;
    use fraction::BigFraction;
    use num_bigint::BigInt;
    use serde_json::{Number, Value};
    use std::cmp::Ordering;
    use test_case::test_case;

    fn number_from_str(raw: &str) -> Number {
        match serde_json::from_str::<Value>(raw).expect("valid JSON number") {
            Value::Number(num) => num,
            _ => unreachable!(),
        }
    }

    #[test_case("18446744073709551616", u64::MAX, Ordering::Greater; "above u64 limit")]
    fn compare_bigint_to_u64_limit(big: &str, limit: u64, expected: Ordering) {
        let big = BigInt::parse_bytes(big.as_bytes(), 10).unwrap();
        assert_eq!(bignum::compare_bigint_to_limit(&big, limit), Some(expected));
    }

    #[test_case("-18446744073709551616", i64::MIN, Ordering::Less; "below i64 limit")]
    fn compare_bigint_to_i64_limit(big: &str, limit: i64, expected: Ordering) {
        let big = BigInt::parse_bytes(big.as_bytes(), 10).unwrap();
        assert_eq!(bignum::compare_bigint_to_limit(&big, limit), Some(expected));
    }

    // Infinity limits come from schema numbers beyond the exponent cap (e.g. `1e2000000`);
    // limits without an exact integer form defer to the caller's f64 comparison.
    #[test_case(f64::INFINITY, Some(Ordering::Less); "infinity limit")]
    #[test_case(f64::NEG_INFINITY, Some(Ordering::Greater); "negative infinity limit")]
    #[test_case(0.5, None; "no exact integer form")]
    fn compare_bigint_to_f64_limit(limit: f64, expected: Option<Ordering>) {
        let big = BigInt::parse_bytes(b"18446744073709551616", 10).unwrap();
        assert_eq!(bignum::compare_bigint_to_limit(&big, limit), expected);
    }

    #[test]
    fn bigint_parses_scientific_integer() {
        let num = number_from_str("1e19");
        let parsed = bignum::try_parse_bigint(&num).expect("parsed bigint");
        assert_eq!(
            parsed,
            BigInt::parse_bytes(b"10000000000000000000", 10).unwrap()
        );
    }

    #[test]
    fn bigint_rejects_non_integer_scientific() {
        let num = number_from_str("1.25e1");
        assert!(bignum::try_parse_bigint(&num).is_none());
    }

    #[test]
    fn bigfraction_parses_scientific_decimal() {
        let num = number_from_str("1.5e-5");
        let parsed = bignum::try_parse_bigfraction(&num).expect("parsed bigfraction");
        let expected =
            BigFraction::from(BigInt::from(3)) / BigFraction::from(BigInt::from(200_000));
        assert_eq!(parsed, expected);
    }

    #[test]
    fn bigfraction_skips_scientific_integer() {
        let num = number_from_str("3e4");
        assert!(bignum::try_parse_bigfraction(&num).is_none());
    }
}

#[cfg(all(test, feature = "arbitrary-precision"))]
mod exact_multiple_of_tests {
    use super::is_multiple_of_integer;
    use serde_json::{Number, Value};
    use test_case::test_case;

    fn number(raw: &str) -> Number {
        match serde_json::from_str::<Value>(raw).expect("valid JSON number") {
            Value::Number(num) => num,
            _ => unreachable!(),
        }
    }

    // Integers past `u64` still divide exactly; rounding them into `f64` first answers about a
    // different number.
    #[test_case("135107988821114880000000000000", 3.0, true; "multiple of three")]
    #[test_case("135107988821114880000000000001", 3.0, false; "one past a multiple of three")]
    #[test_case("135107988821114880000000000002", 3.0, false; "two past a multiple of three")]
    #[test_case("18446744073709551617", 2.0, false; "odd just past u64")]
    #[test_case("18446744073709551618", 2.0, true; "even just past u64")]
    #[test_case("1e30", 3.0, false; "scientific not a multiple")]
    #[test_case("1e30", 2.0, true; "scientific is a multiple")]
    fn exact_beyond_u64(value: &str, divisor: f64, expected: bool) {
        assert_eq!(is_multiple_of_integer(&number(value), divisor), expected);
    }
}