From f19c83b2fdac8094ce36c8579eda98e93ac6fce5 Mon Sep 17 00:00:00 2001 From: Alex Tiernan-Berry Date: Sun, 22 Nov 2026 08:58:35 +0000 Subject: [PATCH 1/2] clazel-js-number: array-backed FixedBig for the exact Number paths Replaces the Vec-backed Big in StringToNumber's fallback, the formatters and the power tables with FixedBig (64 limbs for parsing, 32 otherwise; measured at most 57 and 28). BigInt keeps the unbounded Vec-backed Big, trimmed to the operations it uses. Co-Authored-By: Claude Opus 5.5 --- crates/clazel-js-number/src/bigint.rs | 233 +------- crates/clazel-js-number/src/fixed.rs | 503 ++++++++++++++++++ crates/clazel-js-number/src/format.rs | 6 +- crates/clazel-js-number/src/lib.rs | 1 + crates/clazel-js-number/src/parse.rs | 5 +- crates/clazel-js-number/src/tables.rs | 5 +- crates/clazel-js-number/tests/differential.rs | 5 +- crates/clazel-js-number/tests/fixed.rs | 122 +++++ 8 files changed, 653 insertions(+), 227 deletions(-) create mode 100644 crates/clazel-js-number/src/fixed.rs create mode 100644 crates/clazel-js-number/tests/fixed.rs diff --git a/crates/clazel-js-number/src/bigint.rs b/crates/clazel-js-number/src/bigint.rs index d5990959..d9b3711d 100644 --- a/crates/clazel-js-number/src/bigint.rs +++ b/crates/clazel-js-number/src/bigint.rs @@ -1,12 +1,14 @@ -//! A small unsigned big integer: little-endian `u64` limbs, no trailing zero -//! limb. It holds the exact values the slow paths need (powers of ten and -//! five, scaled mantissas) and nothing more: add and multiply by a word, -//! shifts, comparison, subtraction, and long division. +//! The unbounded unsigned big integer of BigInt values: little-endian `u64` +//! limbs in a `Vec`, no trailing zero limb. It has what BigInt parsing and +//! printing need: multiply and add a word, divide by a word (with the +//! remainder), comparison, and bit access. //! -//! Every operation is total. Preconditions that cannot be stated in the type -//! (`sub_assign` needs `self >= other`; `divrem` needs a nonzero divisor) -//! have a defined answer when violated (`sub_assign` gives zero, `divrem` by -//! zero returns `(0, num)`), so no input panics. +//! The exact paths of the Number conversions use the fixed-capacity, +//! array-backed [`crate::fixed::FixedBig`] instead (Kani cannot reason about +//! `Vec` growth, and those paths are bounded). A BigInt has no bound, so it +//! stays `Vec`-backed. +//! +//! Every operation is total: division by zero leaves the value alone. use std::cmp::Ordering; @@ -17,11 +19,6 @@ pub struct Big { limbs: Vec, } -/// `10^19`, the largest power of ten in a `u64`. -const TEN_19: u64 = 10_000_000_000_000_000_000; -/// `5^27`, the largest power of five in a `u64`. -const FIVE_27: u64 = 7_450_580_596_923_828_125; - /// Append the decimal digits of `v`, padded with zeros on the left to at /// least `width` digits (`v = 0` prints one digit when `width` is 0). pub fn push_u64(s: &mut String, v: u64, width: usize) { @@ -45,12 +42,6 @@ pub fn push_u64(s: &mut String, v: u64, width: usize) { } } -/// A mask of the low `bits` bits. -fn low_mask(bits: u32) -> u64 { - 1u64.checked_shl(bits) - .map_or(u64::MAX, |b| b.wrapping_sub(1)) -} - impl Big { /// Zero. #[must_use] @@ -171,113 +162,6 @@ impl Big { rem as u64 } - /// `self *= 10^k`. - pub fn mul_pow10(&mut self, k: u32) { - let mut k = k; - while k >= 19 { - self.mul_small(TEN_19); - k = k.saturating_sub(19); - } - let mut p: u64 = 1; - for _ in 0..k { - p = p.saturating_mul(10); - } - self.mul_small(p); - } - - /// `self *= 5^k`. - pub fn mul_pow5(&mut self, k: u32) { - let mut k = k; - while k >= 27 { - self.mul_small(FIVE_27); - k = k.saturating_sub(27); - } - let mut p: u64 = 1; - for _ in 0..k { - p = p.saturating_mul(5); - } - self.mul_small(p); - } - - /// `self = floor(self / 5^k)`: floor division composes, so this divides - /// by `5^27` as often as it fits, then by the rest. - pub fn div_pow5(&mut self, k: u32) { - let mut k = k; - while k >= 27 { - self.div_small(FIVE_27); - k = k.saturating_sub(27); - } - let mut p: u64 = 1; - for _ in 0..k { - p = p.saturating_mul(5); - } - self.div_small(p); - } - - /// `self << bits`. - #[must_use] - pub fn shl(&self, bits: u64) -> Self { - if self.is_zero() { - return Self::zero(); - } - let limbs = usize::try_from(bits / 64).unwrap_or(usize::MAX); - let rem = (bits % 64) as u32; - let mut out = vec![0u64; limbs]; - let mut carry: u64 = 0; - for &l in &self.limbs { - if rem == 0 { - out.push(l); - } else { - out.push((l << rem) | carry); - carry = l.checked_shr(64u32.saturating_sub(rem)).unwrap_or(0); - } - } - if carry != 0 { - out.push(carry); - } - let mut b = Self { limbs: out }; - b.trim(); - b - } - - /// `self << 1 | bit`, in place. - fn shl1_or(&mut self, bit: bool) { - let mut carry = u64::from(bit); - for l in &mut self.limbs { - let next = *l >> 63; - *l = (*l << 1) | carry; - carry = next; - } - if carry != 0 { - self.limbs.push(carry); - } - } - - /// `self >> bits`, and whether any bit shifted out was set. - #[must_use] - pub fn shr(&self, bits: u64) -> (Self, bool) { - let limbs = usize::try_from(bits / 64).unwrap_or(usize::MAX); - let rem = (bits % 64) as u32; - let mut sticky = false; - for &l in self.limbs.iter().take(limbs) { - sticky |= l != 0; - } - let kept: Vec = self.limbs.iter().skip(limbs).copied().collect(); - let mut out = Vec::with_capacity(kept.len()); - if rem == 0 { - out.extend_from_slice(&kept); - } else { - sticky |= kept.first().is_some_and(|&l| l & low_mask(rem) != 0); - for (i, &l) in kept.iter().enumerate() { - let next = kept.get(i.saturating_add(1)).copied().unwrap_or(0); - out.push((l >> rem) | next.checked_shl(64u32.saturating_sub(rem)).unwrap_or(0)); - } - } - let mut b = Self { limbs: out }; - b.trim(); - (b, sticky) - } - /// Numeric comparison. #[must_use] pub fn cmp_big(&self, other: &Self) -> Ordering { @@ -294,101 +178,4 @@ impl Big { o => o, } } - - /// `self += other`. - pub fn add_assign(&mut self, other: &Self) { - let mut carry = false; - let n = self.limbs.len().max(other.limbs.len()); - self.limbs.resize(n, 0); - for (i, l) in self.limbs.iter_mut().enumerate() { - let o = other.limbs.get(i).copied().unwrap_or(0); - let (s1, c1) = l.overflowing_add(o); - let (s2, c2) = s1.overflowing_add(u64::from(carry)); - *l = s2; - carry = c1 | c2; - } - if carry { - self.limbs.push(1); - } - self.trim(); - } - - /// `self -= other`. If `other > self` the result is zero. - pub fn sub_assign(&mut self, other: &Self) { - if self.cmp_big(other) == Ordering::Less { - self.limbs.clear(); - return; - } - let mut borrow = false; - for (i, l) in self.limbs.iter_mut().enumerate() { - let o = other.limbs.get(i).copied().unwrap_or(0); - let (d1, b1) = l.overflowing_sub(o); - let (d2, b2) = d1.overflowing_sub(u64::from(borrow)); - *l = d2; - borrow = b1 | b2; - } - self.trim(); - } - - /// Quotient and remainder of `num / den`, by binary long division. - /// Division by zero returns `(0, num)`. - #[must_use] - pub fn divrem(num: &Self, den: &Self) -> (Self, Self) { - if den.is_zero() { - return (Self::zero(), num.clone()); - } - let nbits = num.bit_len(); - let qlimbs = usize::try_from(nbits.div_ceil(64)).unwrap_or(0); - let mut quo = vec![0u64; qlimbs]; - let mut rem = Self::zero(); - let mut i = nbits; - while i > 0 { - i = i.saturating_sub(1); - rem.shl1_or(num.bit(i)); - if rem.cmp_big(den) != Ordering::Less { - rem.sub_assign(den); - let limb = usize::try_from(i / 64).unwrap_or(usize::MAX); - if let Some(q) = quo.get_mut(limb) { - *q |= 1u64 << (i % 64); - } - } - } - let mut q = Self { limbs: quo }; - q.trim(); - (q, rem) - } - - /// The decimal digits, most significant first (`"0"` for zero). - #[must_use] - pub fn to_decimal(&self) -> String { - if self.is_zero() { - return "0".to_string(); - } - let mut t = self.clone(); - let mut chunks: Vec = Vec::new(); - while !t.is_zero() { - chunks.push(t.div_small(TEN_19)); - } - let mut s = String::new(); - for (i, c) in chunks.iter().rev().enumerate() { - push_u64(&mut s, *c, if i == 0 { 0 } else { 19 }); - } - s - } - - /// `5^k`. - #[must_use] - pub fn pow5(k: u32) -> Self { - let mut b = Self::from_u64(1); - b.mul_pow5(k); - b - } - - /// `10^k`. - #[must_use] - pub fn pow10(k: u32) -> Self { - let mut b = Self::from_u64(1); - b.mul_pow10(k); - b - } } diff --git a/crates/clazel-js-number/src/fixed.rs b/crates/clazel-js-number/src/fixed.rs new file mode 100644 index 00000000..bcb73cef --- /dev/null +++ b/crates/clazel-js-number/src/fixed.rs @@ -0,0 +1,503 @@ +//! A fixed-capacity unsigned big integer: `N` little-endian `u64` limbs in an +//! array, and the count of limbs in use. This is the arithmetic of the exact +//! paths of the Number conversions (StringToNumber's fallback, `toFixed`, +//! `toExponential`, `toPrecision` and the power-of-five tables). BigInt values +//! are unbounded and use the `Vec`-backed [`crate::bigint::Big`] instead. +//! +//! Why an array: Kani cannot reason about `Vec` growth. With an array every +//! operation is a loop over at most `N` limbs. +//! +//! Every operation is **total**, and total whatever `N` is, so a proof at a +//! small `N` is a proof about the same generic code that runs at the real `N`: +//! +//! - an operation whose true result needs more than `N` limbs drops the limbs +//! that do not fit and sets [`FixedBig::lost`] (a sticky flag). The value is +//! then wrong but defined, and `lost` says so. Callers size `N` so that it +//! never happens ([`BIG_LIMBS_PARSE`] and [`BIG_LIMBS_FORMAT`]); +//! - `sub_assign` needs `self >= other` and gives zero otherwise; `divrem` +//! by zero returns `(0, num)`; `divrem` is exact only if +//! `den.bit_len() < 64 * N` (the running remainder reaches `2 * den`). +//! +//! Representation invariant (every operation keeps it; the Kani harnesses +//! assert it): `len <= N`; `limbs[len..]` are all zero; if `len > 0` then +//! `limbs[len - 1] != 0`. So zero has `len == 0`, and the derived equality is +//! numeric equality (together with the `lost` flag). + +use std::cmp::Ordering; + +/// Limbs for StringToNumber's exact path (`crate::parse::decimal_exact`). +/// +/// At most 801 significant digits (800 and the sticky digit), then either +/// `* 10^e10` with the value below `10^310` (at most 1030 bits), or a +/// division by `10^-e10` with `-e10 <= 330 + 801 = 1131`: `10^1131` is 3757 +/// bits, the dividend is shifted to 3757 + 55 bits and the running +/// remainder has one more: 3813 bits, 60 limbs. 64 limbs hold 4096 bits. +/// (Measured over the whole test suite: at most 57 limbs.) +pub const BIG_LIMBS_PARSE: usize = 64; +/// Limbs for the formatters and the power-of-five tables. +/// +/// Formatters: the numerator is `m * 2^e2 * 10^scale` and the denominator +/// `2^-e2 * 10^-scale` (each factor only on the side of its sign) for a +/// 53-bit `m`, `e2` in `-1074..=971` and `scale` at most `100 + 324 + 8` +/// (`p <= 101`, a decimal exponent of at least -324, and the loop's eight +/// steps). The worst case is a tiny `x`: the numerator is `53 + 3.33 * 432` +/// bits, 1492 with the shift by one, 24 limbs; the denominator is at most +/// 1075 bits. Tables: `5^342` is 795 bits and the largest dividend is +/// `2^1718`, 27 limbs. 32 limbs hold 2048 bits. (Measured over the whole +/// test suite: at most 28 limbs, counting the pre-trim bound of `shl`, all +/// in the tables.) +pub const BIG_LIMBS_FORMAT: usize = 32; + +/// `10^19`, the largest power of ten in a `u64`. +const TEN_19: u64 = 10_000_000_000_000_000_000; +/// `5^27`, the largest power of five in a `u64`. +const FIVE_27: u64 = 7_450_580_596_923_828_125; + +/// A mask of the low `bits` bits. +fn low_mask(bits: u32) -> u64 { + 1u64.checked_shl(bits) + .map_or(u64::MAX, |b| b.wrapping_sub(1)) +} + +/// An unsigned integer of at most `64 * N` bits. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct FixedBig { + /// Little-endian limbs; the ones from `len` on are zero. + limbs: [u64; N], + /// The number of limbs in use: the last one is nonzero. + len: usize, + /// Whether an operation ever had to drop limbs that did not fit. + lost: bool, +} + +impl FixedBig { + /// Zero. + #[must_use] + pub fn zero() -> Self { + Self { + limbs: [0; N], + len: 0, + lost: false, + } + } + + /// The value `x`. + #[must_use] + pub fn from_u64(x: u64) -> Self { + let mut b = Self::zero(); + b.push(x); + b.trim(); + b + } + + /// The value `x`. + #[must_use] + pub fn from_u128(x: u128) -> Self { + let mut b = Self::zero(); + b.push(x as u64); + b.push((x >> 64) as u64); + b.trim(); + b + } + + /// The value with the limbs `limbs`, least significant first. + #[must_use] + pub fn from_limbs(limbs: [u64; N]) -> Self { + let mut b = Self { + limbs, + len: N, + lost: false, + }; + b.trim(); + b + } + + /// Append the limb `v` (a nonzero one that does not fit sets `lost`). + fn push(&mut self, v: u64) { + match self.limbs.get_mut(self.len) { + Some(slot) => { + *slot = v; + self.len = self.len.saturating_add(1); + } + None => self.lost |= v != 0, + } + } + + /// Drop zero limbs from the top. + fn trim(&mut self) { + while self.len > 0 && self.limbs.get(self.len.saturating_sub(1)) == Some(&0) { + self.len = self.len.saturating_sub(1); + } + } + + /// Whether the value is zero. + #[must_use] + pub fn is_zero(&self) -> bool { + self.len == 0 + } + + /// Whether an operation had to drop limbs that did not fit (the value is + /// then not the true result). + #[must_use] + pub fn lost(&self) -> bool { + self.lost + } + + /// The number of limbs in use. + #[must_use] + pub fn limbs_used(&self) -> usize { + self.len + } + + /// Whether the representation invariant holds (for the Kani harnesses). + #[must_use] + pub fn invariant(&self) -> bool { + self.len <= N + && self.limbs.iter().skip(self.len).all(|&l| l == 0) + && (self.len == 0 + || self + .limbs + .get(self.len.saturating_sub(1)) + .is_some_and(|&l| l != 0)) + } + + /// The number of significant bits (zero for zero). + #[must_use] + pub fn bit_len(&self) -> u64 { + if self.len == 0 { + return 0; + } + let top = self + .limbs + .get(self.len.saturating_sub(1)) + .copied() + .unwrap_or(0); + let below = (self.len as u64).saturating_sub(1).saturating_mul(64); + below.saturating_add(u64::from(64u32.saturating_sub(top.leading_zeros()))) + } + + /// Bit `i` (bit 0 is the least significant). + #[must_use] + pub fn bit(&self, i: u64) -> bool { + let limb = usize::try_from(i / 64).unwrap_or(usize::MAX); + match self.limbs.get(limb) { + Some(&l) => (l >> (i % 64)) & 1 == 1, + None => false, + } + } + + /// The low 128 bits. + #[must_use] + pub fn low_u128(&self) -> u128 { + let lo = self.limbs.first().copied().unwrap_or(0); + let hi = self.limbs.get(1).copied().unwrap_or(0); + u128::from(lo) | (u128::from(hi) << 64) + } + + /// `self *= m`. + pub fn mul_small(&mut self, m: u64) { + let mut carry: u128 = 0; + for l in self.limbs.iter_mut().take(self.len) { + // (2^64-1)^2 + (2^64-1) < 2^128, so this never wraps. + let t = u128::from(*l) + .wrapping_mul(u128::from(m)) + .wrapping_add(carry); + *l = t as u64; + carry = t >> 64; + } + if carry != 0 { + self.push(carry as u64); + } + self.trim(); + } + + /// `self += a`. + pub fn add_small(&mut self, a: u64) { + let mut carry = a; + for l in self.limbs.iter_mut().take(self.len) { + if carry == 0 { + break; + } + let (s, c) = l.overflowing_add(carry); + *l = s; + carry = u64::from(c); + } + if carry != 0 { + self.push(carry); + } + } + + /// `self /= d` for a nonzero word `d`; returns the remainder. Division + /// by zero leaves `self` alone and returns 0. + pub fn div_small(&mut self, d: u64) -> u64 { + if d == 0 { + return 0; + } + let wide = u128::from(d); + let mut rem: u128 = 0; + if let Some(used) = self.limbs.get_mut(..self.len) { + for l in used.iter_mut().rev() { + // rem < d < 2^64, so the shift loses nothing. + let cur = (rem << 64) | u128::from(*l); + *l = cur.checked_div(wide).unwrap_or(0) as u64; + rem = cur.checked_rem(wide).unwrap_or(0); + } + } + self.trim(); + rem as u64 + } + + /// `self *= 10^k`. + pub fn mul_pow10(&mut self, k: u32) { + let mut k = k; + while k >= 19 { + self.mul_small(TEN_19); + k = k.saturating_sub(19); + } + let mut p: u64 = 1; + for _ in 0..k { + p = p.saturating_mul(10); + } + self.mul_small(p); + } + + /// `self *= 5^k`. + pub fn mul_pow5(&mut self, k: u32) { + let mut k = k; + while k >= 27 { + self.mul_small(FIVE_27); + k = k.saturating_sub(27); + } + let mut p: u64 = 1; + for _ in 0..k { + p = p.saturating_mul(5); + } + self.mul_small(p); + } + + /// `self = floor(self / 5^k)`: floor division composes, so this divides + /// by `5^27` as often as it fits, then by the rest. + pub fn div_pow5(&mut self, k: u32) { + let mut k = k; + while k >= 27 { + let _ = self.div_small(FIVE_27); + k = k.saturating_sub(27); + } + let mut p: u64 = 1; + for _ in 0..k { + p = p.saturating_mul(5); + } + let _ = self.div_small(p); + } + + /// Store `v` as limb `i` of a result under construction (`lost` if the + /// limb does not fit and is nonzero). + fn put(&mut self, i: usize, v: u64) { + match self.limbs.get_mut(i) { + Some(slot) => *slot = v, + None => self.lost |= v != 0, + } + } + + /// `self << bits`. + #[must_use] + pub fn shl(&self, bits: u64) -> Self { + let mut out = Self::zero(); + out.lost = self.lost; + if self.is_zero() { + return out; + } + let skip = usize::try_from(bits / 64).unwrap_or(usize::MAX); + let rem = (bits % 64) as u32; + let mut carry: u64 = 0; + let mut at = skip; + for &l in self.limbs.iter().take(self.len) { + if rem == 0 { + out.put(at, l); + } else { + out.put(at, (l << rem) | carry); + carry = l.checked_shr(64u32.saturating_sub(rem)).unwrap_or(0); + } + at = at.saturating_add(1); + } + if carry != 0 { + out.put(at, carry); + } + // Every limb written is at an index of `at` or less. + out.len = at.saturating_add(1).min(N); + out.trim(); + out + } + + /// `self << 1 | bit`, in place. + fn shl1_or(&mut self, bit: bool) { + let mut carry = u64::from(bit); + for l in self.limbs.iter_mut().take(self.len) { + let next = *l >> 63; + *l = (*l << 1) | carry; + carry = next; + } + if carry != 0 { + self.push(carry); + } + } + + /// `self >> bits`, and whether any bit shifted out was set. + #[must_use] + pub fn shr(&self, bits: u64) -> (Self, bool) { + let mut out = Self::zero(); + out.lost = self.lost; + let skip = usize::try_from(bits / 64).unwrap_or(usize::MAX); + let rem = (bits % 64) as u32; + let mut sticky = false; + for &l in self.limbs.iter().take(self.len).take(skip) { + sticky |= l != 0; + } + if rem != 0 { + sticky |= self + .limbs + .get(skip) + .is_some_and(|&l| l & low_mask(rem) != 0); + } + let kept = self.len.saturating_sub(skip); + for i in 0..kept { + let j = skip.saturating_add(i); + let l = self.limbs.get(j).copied().unwrap_or(0); + let w = if rem == 0 { + l + } else { + let next = self.limbs.get(j.saturating_add(1)).copied().unwrap_or(0); + (l >> rem) | next.checked_shl(64u32.saturating_sub(rem)).unwrap_or(0) + }; + out.put(i, w); + } + out.len = kept.min(N); + out.trim(); + (out, sticky) + } + + /// Numeric comparison. + #[must_use] + pub fn cmp_big(&self, other: &Self) -> Ordering { + match self.len.cmp(&other.len) { + Ordering::Equal => { + for (a, b) in self + .limbs + .iter() + .take(self.len) + .rev() + .zip(other.limbs.iter().take(other.len).rev()) + { + match a.cmp(b) { + Ordering::Equal => {} + o => return o, + } + } + Ordering::Equal + } + o => o, + } + } + + /// `self += other`. + pub fn add_assign(&mut self, other: &Self) { + let mut carry = false; + let n = self.len.max(other.len); + // Limbs from `len` on are zero, so the sum needs no special case. + self.len = n; + self.lost |= other.lost; + for (l, &o) in self.limbs.iter_mut().zip(other.limbs.iter()).take(n) { + let (s1, c1) = l.overflowing_add(o); + let (s2, c2) = s1.overflowing_add(u64::from(carry)); + *l = s2; + carry = c1 | c2; + } + if carry { + self.push(1); + } + self.trim(); + } + + /// `self -= other`. If `other > self` the result is zero. + pub fn sub_assign(&mut self, other: &Self) { + if self.cmp_big(other) == Ordering::Less { + self.limbs = [0; N]; + self.len = 0; + return; + } + let mut borrow = false; + for (l, &o) in self.limbs.iter_mut().zip(other.limbs.iter()).take(self.len) { + let (d1, b1) = l.overflowing_sub(o); + let (d2, b2) = d1.overflowing_sub(u64::from(borrow)); + *l = d2; + borrow = b1 | b2; + } + self.trim(); + } + + /// Quotient and remainder of `num / den`, by binary long division. + /// Division by zero returns `(0, num)`. + #[must_use] + pub fn divrem(num: &Self, den: &Self) -> (Self, Self) { + if den.is_zero() { + return (Self::zero(), num.clone()); + } + let nbits = num.bit_len(); + let mut quo = Self::zero(); + let mut rem = Self::zero(); + let mut i = nbits; + while i > 0 { + i = i.saturating_sub(1); + rem.shl1_or(num.bit(i)); + if rem.cmp_big(den) != Ordering::Less { + rem.sub_assign(den); + let limb = usize::try_from(i / 64).unwrap_or(usize::MAX); + if let Some(q) = quo.limbs.get_mut(limb) { + *q |= 1u64 << (i % 64); + } + } + } + // `nbits <= 64 * N`, so the quotient has at most `ceil(nbits / 64)` + // limbs, all of which exist. + quo.len = usize::try_from(nbits.div_ceil(64)).unwrap_or(0).min(N); + quo.trim(); + let lost = num.lost | den.lost | rem.lost; + quo.lost = lost; + rem.lost = lost; + (quo, rem) + } + + /// The decimal digits, most significant first (`"0"` for zero). + #[must_use] + pub fn to_decimal(&self) -> String { + if self.is_zero() { + return "0".to_string(); + } + let mut t = self.clone(); + let mut chunks: Vec = Vec::new(); + while !t.is_zero() { + chunks.push(t.div_small(TEN_19)); + } + let mut s = String::new(); + for (i, c) in chunks.iter().rev().enumerate() { + crate::bigint::push_u64(&mut s, *c, if i == 0 { 0 } else { 19 }); + } + s + } + + /// `5^k`. + #[must_use] + pub fn pow5(k: u32) -> Self { + let mut b = Self::from_u64(1); + b.mul_pow5(k); + b + } + + /// `10^k`. + #[must_use] + pub fn pow10(k: u32) -> Self { + let mut b = Self::from_u64(1); + b.mul_pow10(k); + b + } +} diff --git a/crates/clazel-js-number/src/format.rs b/crates/clazel-js-number/src/format.rs index 316395ab..aa10d485 100644 --- a/crates/clazel-js-number/src/format.rs +++ b/crates/clazel-js-number/src/format.rs @@ -21,7 +21,11 @@ //! `toPrecision` are slow paths, not the hot path of number printing.) //! - Number::toString's shortest digits come from [`crate::shortest`]. -use crate::bigint::{Big, push_u64}; +use crate::bigint::push_u64; +use crate::fixed::{BIG_LIMBS_FORMAT, FixedBig}; + +/// The big integer of the exact formatting arithmetic. +type Big = FixedBig; use crate::shortest::{log10_pow2, shortest_digits}; /// A `RangeError`: an argument outside the range the spec allows. diff --git a/crates/clazel-js-number/src/lib.rs b/crates/clazel-js-number/src/lib.rs index 426aaaa4..d6d707cc 100644 --- a/crates/clazel-js-number/src/lib.rs +++ b/crates/clazel-js-number/src/lib.rs @@ -27,6 +27,7 @@ //! Kani harnesses (compiled only under `cargo kani`). pub mod bigint; +pub mod fixed; pub mod format; pub mod js_bigint; pub mod parse; diff --git a/crates/clazel-js-number/src/parse.rs b/crates/clazel-js-number/src/parse.rs index 81502b5c..f14be01a 100644 --- a/crates/clazel-js-number/src/parse.rs +++ b/crates/clazel-js-number/src/parse.rs @@ -35,7 +35,10 @@ //! - The numeric separator `_` is not accepted (the grammar uses //! `DecimalDigits[~Sep]`). -use crate::bigint::Big; +use crate::fixed::{BIG_LIMBS_PARSE, FixedBig}; + +/// The big integer of the exact path. +type Big = FixedBig; use crate::tables::{EL_MAX_Q, EL_MIN_Q, Tables, tables}; /// The significant digits a decimal is cut to for the exact path. diff --git a/crates/clazel-js-number/src/tables.rs b/crates/clazel-js-number/src/tables.rs index de9637b9..934de29a 100644 --- a/crates/clazel-js-number/src/tables.rs +++ b/crates/clazel-js-number/src/tables.rs @@ -19,7 +19,10 @@ //! (Ulf Adams, "Ryu: fast float-to-string conversion", PLDI 2018, section //! 3, `d2s_full_table.h`.) -use crate::bigint::Big; +use crate::fixed::{BIG_LIMBS_FORMAT, FixedBig}; + +/// The big integer the tables are computed with. +type Big = FixedBig; use std::sync::OnceLock; /// The smallest decimal exponent the Eisel–Lemire table covers. diff --git a/crates/clazel-js-number/tests/differential.rs b/crates/clazel-js-number/tests/differential.rs index 61ea628f..09b8fb15 100644 --- a/crates/clazel-js-number/tests/differential.rs +++ b/crates/clazel-js-number/tests/differential.rs @@ -13,12 +13,15 @@ //! `tail`, `split`, `parse_f64`) stand in for slicing and `unwrap`: a failed //! lookup gives an empty string or NaN, and the assertion that follows fails. -use clazel_js_number::bigint::Big; +use clazel_js_number::fixed::FixedBig; use clazel_js_number::shortest::shortest_digits; use clazel_js_number::{ RangeError, number_to_string, string_to_number, to_exponential, to_fixed, to_precision, }; +/// Room for the exact decimal expansions of the midpoints (about 2,600 bits). +type Big = FixedBig<64>; + /// SplitMix64 (Steele, Lea and Flood 2014): a fixed-seed generator, so a /// failure reproduces. struct Rng(u64); diff --git a/crates/clazel-js-number/tests/fixed.rs b/crates/clazel-js-number/tests/fixed.rs new file mode 100644 index 00000000..1051cb8d --- /dev/null +++ b/crates/clazel-js-number/tests/fixed.rs @@ -0,0 +1,122 @@ +//! `FixedBig<2>` against `u128` arithmetic, including the cases where the +//! result does not fit and `lost` must say so. + +use clazel_js_number::fixed::FixedBig; +use std::cmp::Ordering; + +type B = FixedBig<2>; + +/// SplitMix64: a fixed-seed generator, so a failure reproduces. +struct Rng(u64); + +impl Rng { + fn next(&mut self) -> u64 { + self.0 = self.0.wrapping_add(0x9E37_79B9_7F4A_7C15); + let mut z = self.0; + z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9); + z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB); + z ^ (z >> 31) + } + /// A value with a random bit length, so short values are common. + fn wide(&mut self) -> u128 { + let v = (u128::from(self.next()) << 64) | u128::from(self.next()); + v.checked_shr((self.next() % 128) as u32).unwrap_or(0) + } +} + +#[test] +fn matches_u128() { + let mut rng = Rng(0x00F1_8ED0_0000_0001); + let n = if cfg!(miri) { 20 } else { 200_000 }; + for _ in 0..n { + let x = rng.wide(); + let y = rng.wide(); + let w = rng.next(); + let ww = u128::from(w); + let bx = B::from_u128(x); + let by = B::from_u128(y); + assert!(bx.invariant() && by.invariant()); + assert_eq!(bx.low_u128(), x); + assert_eq!(bx.bit_len(), u64::from(128 - x.leading_zeros())); + assert_eq!(bx.cmp_big(&by), x.cmp(&y)); + assert_eq!(bx.cmp_big(&bx), Ordering::Equal); + + let mut s = bx.clone(); + s.add_assign(&by); + assert!(s.invariant()); + assert_eq!(s.low_u128(), x.wrapping_add(y)); + assert_eq!(s.lost(), x.checked_add(y).is_none()); + + let mut d = bx.clone(); + d.sub_assign(&by); + assert!(d.invariant()); + assert_eq!(d.low_u128(), x.saturating_sub(y)); + assert!(!d.lost()); + + let mut m = bx.clone(); + m.mul_small(w); + assert!(m.invariant()); + assert_eq!(m.low_u128(), x.wrapping_mul(ww)); + assert_eq!(m.lost(), x.checked_mul(ww).is_none()); + + let mut a = bx.clone(); + a.add_small(w); + assert!(a.invariant()); + assert_eq!(a.low_u128(), x.wrapping_add(ww)); + assert_eq!(a.lost(), x.checked_add(ww).is_none()); + + let mut q = bx.clone(); + let r = q.div_small(w); + assert!(q.invariant()); + if w == 0 { + assert_eq!((q.low_u128(), r), (x, 0)); + } else { + assert_eq!(q.low_u128(), x.checked_div(ww).unwrap_or(0)); + assert_eq!(u128::from(r), x.checked_rem(ww).unwrap_or(0)); + } + + let sh = rng.next() % 140; + let shu = sh as u32; + let l = bx.shl(sh); + assert!(l.invariant()); + let shifted = x.checked_shl(shu).unwrap_or(0); + let fits = sh < 128 && shifted.checked_shr(shu) == Some(x); + assert_eq!(l.lost(), !fits && x != 0); + if sh < 128 { + assert_eq!(l.low_u128(), shifted); + } + let (rs, sticky) = bx.shr(sh); + assert!(rs.invariant()); + if sh < 128 { + assert_eq!(rs.low_u128(), x.checked_shr(shu).unwrap_or(0)); + let mask = 1u128.checked_shl(shu).unwrap_or(0).wrapping_sub(1); + assert_eq!(sticky, x & mask != 0); + } else { + assert_eq!(rs.low_u128(), 0); + assert_eq!(sticky, x != 0); + } + + // divrem is exact while the divisor leaves a spare bit. + if y != 0 && y < 1 << 127 { + let (qq, rr) = B::divrem(&bx, &by); + assert!(qq.invariant() && rr.invariant()); + assert_eq!(qq.low_u128(), x.checked_div(y).unwrap_or(0)); + assert_eq!(rr.low_u128(), x.checked_rem(y).unwrap_or(0)); + assert!(!qq.lost()); + } + let (z, same) = B::divrem(&bx, &B::zero()); + assert!(z.is_zero()); + assert_eq!(same, bx); + } +} + +#[test] +fn zero_and_decimal() { + assert!(B::zero().is_zero()); + assert_eq!(B::zero().to_decimal(), "0"); + assert_eq!(B::from_u128(u128::MAX).to_decimal(), u128::MAX.to_string()); + assert!(!B::from_u128(u128::MAX).lost()); + // 10^40 does not fit in 128 bits. + assert!(B::pow10(40).lost()); + assert!(!B::pow10(38).lost()); +} From f590b5017f1e9025d898937bb783800e820a9b35 Mon Sep 17 00:00:00 2001 From: Alex Tiernan-Berry Date: Sun, 22 Nov 2026 10:46:14 +0000 Subject: [PATCH 2/2] clazel-js-number: Kani harnesses for FixedBig and StringToNumber on bytes Byte-level trim and digit helpers replace the str/char calls that crashed the Kani compiler. Kani found add_small leaving a zero top limb on carry-out; fixed. The proofs header lists what is proven, at which bounds, and what is not. Co-Authored-By: Claude Opus 5.5 --- crates/clazel-js-number/README.md | 8 +- crates/clazel-js-number/src/fixed.rs | 2 + crates/clazel-js-number/src/format.rs | 13 +- crates/clazel-js-number/src/lib.rs | 2 +- crates/clazel-js-number/src/parse.rs | 106 +++++++- crates/clazel-js-number/src/proofs.rs | 339 +++++++++++++++++++++++--- crates/clazel-js-number/tests/trim.rs | 58 +++++ 7 files changed, 470 insertions(+), 58 deletions(-) create mode 100644 crates/clazel-js-number/tests/trim.rs diff --git a/crates/clazel-js-number/README.md b/crates/clazel-js-number/README.md index e2c2a100..fa36e126 100644 --- a/crates/clazel-js-number/README.md +++ b/crates/clazel-js-number/README.md @@ -13,8 +13,10 @@ Part of [Clazel](../../README.md). ECMAScript's Number conversions | `bigint_literal_value(&str) -> Option` | The value of a lexer BigInt literal (`n` suffix, `_` separators, §12.9.3†). | | `BigInt::to_string_radix(u32)` | BigInt::toString (§6.1.6.2.23†), radix 2 to 36, lowercase; `RangeError` outside that. | -`BigInt` is a sign and a `Big` magnitude (zero is never negative), so the limb -arithmetic exists once. Conversion takes a word-sized chunk of digits at a +`BigInt` is a sign and a `Big` magnitude (zero is never negative, unbounded, +`Vec`-backed). The Number conversions use the fixed-capacity `FixedBig` +instead (64 limbs for StringToNumber's exact path, 32 for the formatters and +the tables), which Kani can reason about. Conversion takes a word-sized chunk of digits at a time (quadratic), with a bit-extraction path for radix 2, 4, 8, 16 and 32. † The section numbers are from `phase-7.md`; the spec text is not vendored, so @@ -46,7 +48,7 @@ Raising the tier to 1 waits for CI's full verification on the pull request. - Heap storage for BigInts (item 7.5): this crate parses and prints them. - Number::toString for a radix other than 10. -- The powers-of-five tables are computed on first use from `Big`, not stored. +- The powers-of-five tables are computed on first use from `FixedBig`, not stored. A later change can emit them as a checked-in constant, as `cargo xtask tables` does for IDNA. diff --git a/crates/clazel-js-number/src/fixed.rs b/crates/clazel-js-number/src/fixed.rs index bcb73cef..ef10d79d 100644 --- a/crates/clazel-js-number/src/fixed.rs +++ b/crates/clazel-js-number/src/fixed.rs @@ -225,6 +225,8 @@ impl FixedBig { if carry != 0 { self.push(carry); } + // A carry that did not fit leaves the top limb zero (found by Kani). + self.trim(); } /// `self /= d` for a nonzero word `d`; returns the remainder. Division diff --git a/crates/clazel-js-number/src/format.rs b/crates/clazel-js-number/src/format.rs index aa10d485..b2c21b81 100644 --- a/crates/clazel-js-number/src/format.rs +++ b/crates/clazel-js-number/src/format.rs @@ -124,10 +124,13 @@ fn decompose(x: f64) -> (u64, i64) { } /// The integer nearest to `x * 10^scale`, the larger one on a tie. -fn scaled_round(x: f64, scale: i64) -> Big { +/// +/// Generic in the limb count `N` so that the Kani harnesses run the same code +/// at a small `N` (too few limbs gives a wrong but defined answer). +pub(crate) fn scaled_round(x: f64, scale: i64) -> FixedBig { let (m, e2) = decompose(x); - let mut num = Big::from_u64(m); - let mut den = Big::from_u64(1); + let mut num = FixedBig::::from_u64(m); + let mut den = FixedBig::::from_u64(1); if e2 >= 0 { num = num.shl(e2.unsigned_abs()); } else { @@ -142,7 +145,7 @@ fn scaled_round(x: f64, scale: i64) -> Big { // floor((2 num + den) / (2 den)) is round-half-up of num / den. let mut twice = num.shl(1); twice.add_assign(&den); - Big::divrem(&twice, &den.shl(1)).0 + FixedBig::::divrem(&twice, &den.shl(1)).0 } /// The `p` digits `n` and the exponent `e` of the spec's "let e and n be @@ -199,7 +202,7 @@ pub fn to_fixed(x: f64, fraction_digits: i64) -> Result { } // 9.a.: "let n be an integer for which n / 10^f - x is as close to zero // as possible. If there are two such n, pick the larger n." - let n = scaled_round(x, f); + let n = scaled_round::(x, f); let mut m = n.to_decimal(); let f = usize::try_from(f).unwrap_or(0); // 10. "If f != 0, then let k be the length of m; if k <= f, then let z diff --git a/crates/clazel-js-number/src/lib.rs b/crates/clazel-js-number/src/lib.rs index d6d707cc..d1aecd0e 100644 --- a/crates/clazel-js-number/src/lib.rs +++ b/crates/clazel-js-number/src/lib.rs @@ -12,7 +12,7 @@ //! - [`number_to_string`]: the shortest digits that round-trip, by Ryū //! ([`shortest`]), laid out as the spec says ([`format`]). //! - [`to_fixed`], [`to_exponential`], [`to_precision`]: exact, by big -//! integers ([`format`], [`bigint`]). +//! integers ([`format`], [`fixed`]). //! //! - [`string_to_bigint`], [`bigint_literal_value`] and //! [`BigInt::to_string_radix`]: StringToBigInt §7.1.14†, the value of a diff --git a/crates/clazel-js-number/src/parse.rs b/crates/clazel-js-number/src/parse.rs index f14be01a..ea276a1e 100644 --- a/crates/clazel-js-number/src/parse.rs +++ b/crates/clazel-js-number/src/parse.rs @@ -36,9 +36,6 @@ //! `DecimalDigits[~Sep]`). use crate::fixed::{BIG_LIMBS_PARSE, FixedBig}; - -/// The big integer of the exact path. -type Big = FixedBig; use crate::tables::{EL_MAX_Q, EL_MIN_Q, Tables, tables}; /// The significant digits a decimal is cut to for the exact path. @@ -314,7 +311,15 @@ pub(crate) fn leading_digits(d: &Decimal<'_>) -> (u64, i64, bool) { /// The nearest `f64` to `d` (not negative), by exact big-integer arithmetic. #[must_use] pub fn decimal_exact(d: &Decimal<'_>) -> f64 { - let mut big = Big::zero(); + decimal_exact_in::(d) +} + +/// [`decimal_exact`] with `N` limbs of big integer. `N` is a parameter so +/// that the Kani harnesses run the same code at a small `N`; with fewer +/// limbs than the input needs the answer is wrong but defined. +#[must_use] +pub fn decimal_exact_in(d: &Decimal<'_>) -> f64 { + let mut big = FixedBig::::zero(); let mut taken: usize = 0; let mut dropped: i64 = 0; let mut sticky = false; @@ -363,7 +368,7 @@ pub fn decimal_exact(d: &Decimal<'_>) -> f64 { let (hi, st) = big.shr(bl.saturating_sub(64)); return round_to_f64(hi.low_u128() as u64, bl.saturating_sub(64) as i64, st); } - let p = Big::pow10(u32::try_from(e10.saturating_neg()).unwrap_or(0)); + let p = FixedBig::::pow10(u32::try_from(e10.saturating_neg()).unwrap_or(0)); // Scale so the quotient has 55 or 56 bits, more than a double needs. let s = (p.bit_len() as i64) .saturating_sub(big.bit_len() as i64) @@ -373,13 +378,20 @@ pub fn decimal_exact(d: &Decimal<'_>) -> f64 { } else { (big, p.shl(s.unsigned_abs())) }; - let (quo, rem) = Big::divrem(&num, &den); + let (quo, rem) = FixedBig::::divrem(&num, &den); round_to_f64(quo.low_u128() as u64, s.saturating_neg(), !rem.is_zero()) } /// The nearest `f64` to `d` (not negative), using `t` for Eisel–Lemire. #[must_use] pub fn decimal_to_f64(d: &Decimal<'_>, t: &Tables) -> f64 { + decimal_to_f64_in::(d, t) +} + +/// [`decimal_to_f64`] with `N` limbs for the exact path (see +/// [`decimal_exact_in`]). +#[must_use] +pub fn decimal_to_f64_in(d: &Decimal<'_>, t: &Tables) -> f64 { let (w, q, truncated) = leading_digits(d); if w == 0 { return 0.0; @@ -413,7 +425,19 @@ pub fn decimal_to_f64(d: &Decimal<'_>, t: &Tables) -> f64 { } } } - decimal_exact(d) + decimal_exact_in::(d) +} + +/// The value of the ASCII digit `c` (`0-9`, `a-f`, `A-F`) if it is below +/// `radix`: `char::to_digit` for the radixes 2 to 16, on bytes. +fn digit_in_radix(c: u8, radix: u32) -> Option { + let v = match c { + b'0'..=b'9' => u32::from(c.wrapping_sub(b'0')), + b'a'..=b'f' => u32::from(c.wrapping_sub(b'a')).saturating_add(10), + b'A'..=b'F' => u32::from(c.wrapping_sub(b'A')).saturating_add(10), + _ => return None, + }; + (v < radix).then_some(v) } /// The value of the digits of `b` in radix `1 << bits` (`bits` in 1..=4), @@ -428,7 +452,7 @@ pub(crate) fn radix_value(b: &[u8], bits: u32) -> Option { let mut sticky = false; let mut full = false; for &c in b { - let v = char::from(c).to_digit(radix)?; + let v = digit_in_radix(c, radix)?; if full { sticky |= v != 0; exp2 = exp2.saturating_add(i64::from(bits)); @@ -452,7 +476,69 @@ pub(crate) fn radix_value(b: &[u8], bits: u32) -> Option { /// StringToNumber (§7.1.4.1.1†): the Number value of `s`, or NaN. #[must_use] pub fn string_to_number(s: &str) -> f64 { - let t = s.trim_matches(is_str_whitespace).as_bytes(); + string_to_number_bytes::(s.as_bytes(), tables()) +} + +/// The length in bytes of the StrWhiteSpace character at the start of `b` +/// (UTF-8), or 0 if there is none: the code points of [`is_str_whitespace`]. +fn leading_whitespace(b: &[u8]) -> usize { + match b { + [0x09..=0x0D | 0x20, ..] => 1, + [0xC2, 0xA0, ..] => 2, + [0xE1, 0x9A, 0x80, ..] + | [0xE2, 0x80, 0x80..=0x8A | 0xA8 | 0xA9 | 0xAF, ..] + | [0xE2, 0x81, 0x9F, ..] + | [0xE3, 0x80, 0x80, ..] + | [0xEF, 0xBB, 0xBF, ..] => 3, + _ => 0, + } +} + +/// The length in bytes of the StrWhiteSpace character at the end of `b`. +fn trailing_whitespace(b: &[u8]) -> usize { + match b { + [.., 0x09..=0x0D | 0x20] => 1, + [.., 0xC2, 0xA0] => 2, + [.., 0xE1, 0x9A, 0x80] + | [.., 0xE2, 0x80, 0x80..=0x8A | 0xA8 | 0xA9 | 0xAF] + | [.., 0xE2, 0x81, 0x9F] + | [.., 0xE3, 0x80, 0x80] + | [.., 0xEF, 0xBB, 0xBF] => 3, + _ => 0, + } +} + +/// `b` (the UTF-8 of a string) without its leading and trailing +/// StrWhiteSpace: `str::trim_matches(is_str_whitespace)` on bytes, so that +/// the conversion below is a function of bytes and Kani never meets `char` +/// decoding. (The tests compare the two on every code point.) +#[must_use] +pub fn trim_str_whitespace(b: &[u8]) -> &[u8] { + let mut t = b; + loop { + let n = leading_whitespace(t); + if n == 0 { + break; + } + t = t.get(n..).unwrap_or(&[]); + } + loop { + let n = trailing_whitespace(t); + if n == 0 { + break; + } + t = t.get(..t.len().saturating_sub(n)).unwrap_or(&[]); + } + t +} + +/// StringToNumber on the UTF-8 bytes of the string, with `t` for +/// Eisel–Lemire and `N` limbs for the exact path ([`decimal_exact_in`]). +/// Bytes that are not UTF-8 are not whitespace and not part of a literal, +/// so they give NaN, as `string_to_number` would for the same text. +#[must_use] +pub fn string_to_number_bytes(s: &[u8], tbl: &Tables) -> f64 { + let t = trim_str_whitespace(s); if t.is_empty() { return 0.0; } @@ -477,7 +563,7 @@ pub fn string_to_number(s: &str) -> f64 { f64::INFINITY } else { match scan_decimal(body) { - Some(d) => decimal_to_f64(&d, tables()), + Some(d) => decimal_to_f64_in::(&d, tbl), None => return f64::NAN, } }; diff --git a/crates/clazel-js-number/src/proofs.rs b/crates/clazel-js-number/src/proofs.rs index 29a7034a..9a214188 100644 --- a/crates/clazel-js-number/src/proofs.rs +++ b/crates/clazel-js-number/src/proofs.rs @@ -4,57 +4,126 @@ //! (symbolic, not sampled), that the functions named never panic, never //! overflow (the crate is built with overflow checks, so an overflowing //! operation is a failed assertion), and never index out of bounds; and, -//! where an oracle is cheap, that the answer is right: +//! where an oracle is cheap, that the answer is right. //! -//! - `Big::add_small` against `u128` addition; -//! - `round_to_f64` for every `q`, `exp2` and `sticky`: total, and never -//! NaN or negative; -//! - `eisel_lemire` for every `w`, `q` and every table entry with its top -//! bit set (as every real entry has): total, never NaN or negative. That -//! no table value can make it overflow is this proof; that the real table -//! is right is the differential tests' job; -//! - `mul_shift` (every 57-bit `m`, 125-bit `mul` and shift), -//! `log10_pow2`, `log10_pow5` and `pow5bits`; -//! - `scan_decimal` on every byte string of up to 5 bytes, `leading_digits` -//! on every 3 + 3 digit literal with any exponent, and `radix_value` on -//! every 3-byte string in each radix. +//! # `FixedBig`, the array-backed big integer of the Number conversions //! -//! - on `Big` of up to two limbs (any `u128`): `mul_small` and `div_small` -//! (any word, zero included) are total; `cmp_big` is `u128` order; -//! `bit_len` and `bit` (any index) match `u128`. +//! `FixedBig` (`fixed.rs`) holds `N` limbs in an array and the count in +//! use; an operation whose result needs more limbs drops them and sets a +//! `lost` flag, so every operation is total at every `N`. The harnesses run +//! it at `N` = 1, 2 and 3, not at the real sizes (64 limbs for StringToNumber's +//! exact path, 32 for the formatters and tables: they were sized by argument +//! and by measurement, see `fixed.rs`). The code is the same generic code at +//! every `N`: every limb access is a `get`, `take` or `zip`, and `N` appears +//! only as the array length and in `min(N)`, so what is shown at `N` = 2 or 3 +//! for totality holds at `N` = 64. That is an argument, not a Kani result, and +//! the differential tests (`tests/fixed.rs` against `u128` with `N` = 2, +//! `tests/differential.rs` at the real sizes) are the evidence behind it. //! -//! Harnesses that were written and did not finish within 100 s to 400 s (on -//! a loaded laptop; Kani reports a CBMC timeout as FAILED, not as a -//! counterexample) were removed rather than left failing: `Big`'s `shl` and -//! `shr` (even for a shift under 64), `add_assign` (even on one-limb -//! inputs), `sub_assign`, `divrem`, `mul_small` and `div_small` checked -//! against `u128` arithmetic, Ryu's `d2d_with` as a whole, and -//! `layout_decimal` (string building). `string_to_number` over a two-byte -//! `&str` crashed the Kani compiler (an internal error in its intrinsics -//! pass) before it ran. So these are **not** proven panic-free by Kani: -//! `decimal_exact`, `string_to_number`, `number_to_string`, the three `to_*` -//! formatters, `Big` beyond the operations above, and `d2d_with`. The -//! differential tests (`tests/differential.rs`, with overflow checks on) -//! exercise them; that is evidence, not proof. +//! Proven on symbolic contents, each keeping the representation invariant +//! (`FixedBig::invariant`: `len <= N`, limbs from `len` on zero, top limb +//! nonzero): //! -//! BigInt parsing and printing (`js_bigint`): proven are `digit_value` and -//! `digit_char` (total, below 36, mutually inverse, exactly the ASCII -//! alphanumerics), `chunk_power` (the largest power of each radix 2 to 36 -//! in a `u64`), and one-limb `mul_small` then `add_small` against `u128` -//! arithmetic (31 s). Written and stopped after more than 3 minutes, so -//! removed: one-limb `div_small` against `u64` division (a 128-by-64-bit -//! division) and `push_chunk` (a 64-step loop of `u64` division). Not proven: +//! - `from_u128`, `low_u128`, `bit_len`, `bit` against `u128` (`N` = 2); +//! `cmp_big` is `u128` order; +//! - `add_small`, `add_assign` against `u128` addition, and `lost` exactly on +//! carry out; `sub_assign` against saturating `u128` subtraction; +//! - `mul_small`: one-limb value times a word equals the `u128` product; +//! total on any three limbs times any word; +//! - `div_small`: total on any three limbs and any word, zero included, with +//! the remainder below the divisor; +//! - `shl` (any shift of a `u64`, equal to the `u128` shift when it is below +//! 64) and `shr` (any shift of a `u128`, with the sticky bit); both total +//! on any three limbs and any shift. +//! +//! Kani found one real bug here: `add_small` with a carry out of the top limb +//! left a zero top limb (invariant broken, only when the value did not fit). +//! Fixed by trimming. +//! +//! **Not proven by Kani**: `divrem` (its loop runs once per bit of the +//! dividend; one limb with a free dividend did not finish in 12 minutes, and +//! one limb with a dividend under 2^12 did not in 8), `mul_pow10`, +//! `mul_pow5`, `div_pow5` (each is a loop whose counter falls by saturating +//! subtraction around `mul_small`/`div_small`, but at `N` = 2 with `k` up to +//! 40 the multiplications did not finish in 7 minutes), `to_decimal`. They are +//! checked by `tests/fixed.rs` (`divrem`, against `u128`) and the +//! differential tests. +//! +//! # StringToNumber +//! +//! `string_to_number(&str)` is `string_to_number_bytes(s.as_bytes(), tables())`, +//! on bytes: the old `&str` version crashed the Kani compiler in `char` +//! decoding (`trim_matches` over `char`s and `char::to_digit`), so trimming is +//! now `trim_str_whitespace` on UTF-8 bytes and radix digits are +//! `digit_in_radix` (`tests/trim.rs` compares the trimmer with +//! `trim_matches(is_str_whitespace)` on every Unicode scalar value). +//! +//! - `string_to_number_bytes::<2>` with a table that has no Eisel-Lemire +//! entry: total on every byte string of up to 3 bytes over a 12-byte +//! alphabet (digits 0, 1, 9; both signs; `.`; `e`; space; `x`; `I`; the +//! bytes `E2` and `80`). That covers whitespace trimming, signs, the radix +//! prefix, `Infinity`'s first letter, `scan_decimal` and Clinger's fast +//! path. A three-byte literal never reaches the exact path (`decimal_exact` +//! needs a decimal exponent beyond 22 or more than 15 significant digits), +//! so that path is not covered by this harness. +//! - Also: `round_to_f64` (every `q`, `exp2`, `sticky`), `eisel_lemire` (every +//! `w`, `q` and every table entry with its top bit set), `scan_decimal` on +//! every byte string of up to 5 bytes, `leading_digits` on every 3 + 3 digit +//! literal with any exponent, and `radix_value` on every 3-byte string in +//! each radix. +//! +//! **Not proven by Kani**: `decimal_exact` (the exact fallback): a harness for +//! one digit times `10^exp`, `exp` in 0..=400 on two limbs, did not finish in +//! 12 minutes; neither did 0..=40 nor 0..=18. Negative exponents also need +//! `divrem`. So `string_to_number` is **not** proven panic-free overall. +//! `tables()` (the powers-of-five tables, built once from `FixedBig` by +//! loops over about 700 entries) is not proven either. A CBMC timeout is +//! reported by Kani as FAILED, not as a counterexample; none of the harnesses +//! that were dropped produced a counterexample. +//! +//! # Number to string, `toFixed`, `toExponential`, `toPrecision` +//! +//! Proven: `mul_shift` (every 57-bit `m`, 125-bit `mul` and shift), +//! `log10_pow2`, `log10_pow5` and `pow5bits`. +//! +//! **Not proven by Kani**: `number_to_string`, `to_fixed`, `to_exponential`, +//! `to_precision`, `scaled_round`, `exponent_digits`, `layout_decimal` +//! (`String` building), and Ryu's `d2d_with` as a whole (written and stopped +//! after more than 400 s). A harness for `scaled_round` at two limbs with +//! `divrem` replaced by a stub that returns any value (Kani's unstable +//! stubbing, which `cargo kani -p` does not enable) did not finish in 6 +//! minutes. The differential tests (`tests/differential.rs`: every `f32` +//! widened, 300,000 random doubles, `toFixed`/`toExponential`/`toPrecision` +//! against Rust's `{:.*}` and `{:.*e}`, with overflow checks on) exercise them; +//! that is evidence, not proof. +//! +//! # BigInt (`js_bigint`, the `Vec`-backed `bigint::Big`) +//! +//! Proven: `digit_value` and `digit_char` (total, below 36, mutually inverse, +//! exactly the ASCII alphanumerics), `chunk_power` (the largest power of each +//! radix 2 to 36 in a `u64`), `Big`'s `mul_small` and `div_small` total on any +//! two limbs, `cmp_big` is `u128` order and `bit_len`/`bit` match `u128`, and +//! one-limb `mul_small` then `add_small` against `u128` arithmetic. +//! `Big::add_small` against `u128` addition. BigInt magnitudes are unbounded, +//! so `Big` stays `Vec`-backed, and Kani cannot grow a `Vec` symbolically: //! `parse_magnitude`, `magnitude_digits`, `string_to_bigint`, -//! `bigint_literal_value`, `BigInt::to_string_radix`; `tests/bigint.rs` -//! exercises them against an independent reference. +//! `bigint_literal_value` and `BigInt::to_string_radix` are **not** proven; +//! `tests/bigint.rs` exercises them against an independent reference. +//! One-limb `div_small` against `u64` division and `push_chunk` (a 64-step +//! loop of `u64` division) were stopped after more than 3 minutes. +//! +//! So `clazel-js-number` stays at tier 0: no public conversion is proven free +//! of panics and overflow. use crate::bigint::Big; +use crate::fixed::FixedBig; use crate::js_bigint::{chunk_power, digit_char, digit_value}; use crate::parse::{ Decimal, eisel_lemire, leading_digits, radix_value, round_to_f64, scan_decimal, + string_to_number_bytes, }; use crate::shortest::{log10_pow2, log10_pow5, mul_shift}; -use crate::tables::pow5bits; +use crate::tables::{Tables, pow5bits}; #[kani::proof] #[kani::unwind(4)] @@ -263,3 +332,195 @@ fn big_bit_len_and_bit_match_u128() { let want = i < 128 && (x >> i) & 1 == 1; assert!(b.bit(i) == want); } + +// ---- `FixedBig` (array-backed): the same generic code at small `N` ---- + +type B1 = FixedBig<1>; +type B2 = FixedBig<2>; +type B3 = FixedBig<3>; + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_from_u128_is_u128() { + let x: u128 = kani::any(); + let i: u64 = kani::any(); + let b = B2::from_u128(x); + assert!(b.invariant() && !b.lost()); + assert!(b.low_u128() == x); + assert!(b.bit_len() == u64::from(128 - x.leading_zeros())); + assert!(b.bit(i) == (i < 128 && (x >> i) & 1 == 1)); + assert!(b.is_zero() == (x == 0)); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_cmp_is_u128_order() { + let x: u128 = kani::any(); + let y: u128 = kani::any(); + assert!(B2::from_u128(x).cmp_big(&B2::from_u128(y)) == x.cmp(&y)); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_add_small_is_u128_sum() { + let x: u128 = kani::any(); + let a: u64 = kani::any(); + let mut b = B2::from_u128(x); + b.add_small(a); + assert!(b.invariant()); + assert!(b.low_u128() == x.wrapping_add(u128::from(a))); + assert!(b.lost() == x.checked_add(u128::from(a)).is_none()); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_mul_small_is_total() { + // Three limbs of any value times any word: total, invariant kept. + let x: [u64; 3] = kani::any(); + let m: u64 = kani::any(); + let mut b = B3::from_limbs(x); + b.mul_small(m); + assert!(b.invariant()); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_mul_small_one_limb_is_u128_product() { + let x: u64 = kani::any(); + let m: u64 = kani::any(); + let mut b = B2::from_u64(x); + b.mul_small(m); + assert!(b.invariant() && !b.lost()); + assert!(b.low_u128() == u128::from(x) * u128::from(m)); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_div_small_is_total() { + let x: [u64; 3] = kani::any(); + let d: u64 = kani::any(); + let mut b = B3::from_limbs(x); + let r = b.div_small(d); + assert!(b.invariant()); + assert!(d == 0 || r < d); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_shl_is_total_and_u128_shift() { + let x: u64 = kani::any(); + let bits: u64 = kani::any(); + let b = B2::from_u64(x); + let s = b.shl(bits); + assert!(s.invariant()); + if bits < 64 { + assert!(s.low_u128() == u128::from(x) << bits); + assert!(!s.lost()); + } +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_shl_three_limbs_is_total() { + let x: [u64; 3] = kani::any(); + let bits: u64 = kani::any(); + let s = B3::from_limbs(x).shl(bits); + assert!(s.invariant()); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_shr_is_u128_shift() { + let x: u128 = kani::any(); + let bits: u64 = kani::any(); + let (s, sticky) = B2::from_u128(x).shr(bits); + assert!(s.invariant() && !s.lost()); + if bits < 128 { + assert!(s.low_u128() == x >> bits); + assert!(sticky == (x & ((1u128 << bits) - 1) != 0)); + } else { + assert!(s.is_zero() && sticky == (x != 0)); + } +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_shr_three_limbs_is_total() { + let x: [u64; 3] = kani::any(); + let bits: u64 = kani::any(); + let (s, _) = B3::from_limbs(x).shr(bits); + assert!(s.invariant()); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_add_assign_is_u128_sum() { + let x: u128 = kani::any(); + let y: u128 = kani::any(); + let mut b = B2::from_u128(x); + b.add_assign(&B2::from_u128(y)); + assert!(b.invariant()); + assert!(b.low_u128() == x.wrapping_add(y)); + assert!(b.lost() == x.checked_add(y).is_none()); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_add_assign_three_limbs_is_total() { + let x: [u64; 3] = kani::any(); + let y: [u64; 3] = kani::any(); + let mut b = B3::from_limbs(x); + b.add_assign(&B3::from_limbs(y)); + assert!(b.invariant()); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_sub_assign_is_u128_difference() { + let x: u128 = kani::any(); + let y: u128 = kani::any(); + let mut b = B2::from_u128(x); + b.sub_assign(&B2::from_u128(y)); + assert!(b.invariant() && !b.lost()); + assert!(b.low_u128() == x.saturating_sub(y)); +} + +#[kani::proof] +#[kani::unwind(5)] +fn fixed_sub_assign_three_limbs_is_total() { + let x: [u64; 3] = kani::any(); + let y: [u64; 3] = kani::any(); + let mut b = B3::from_limbs(x); + b.sub_assign(&B3::from_limbs(y)); + assert!(b.invariant()); +} + +// ---- StringToNumber on bytes ---- + +/// Tables with no Eisel-Lemire entry: every decimal that Clinger's fast path +/// does not take goes to the exact path. +fn no_tables() -> Tables { + Tables { + el: Vec::new(), + pow5_split: Vec::new(), + pow5_inv_split: Vec::new(), + } +} + +#[kani::proof] +#[kani::unwind(6)] +fn string_to_number_bytes_three_bytes_is_total() { + // Every byte string of up to 3 bytes over an alphabet that has a digit, + // each sign, the point, both exponent letters, the radix letter, a space, + // two bytes of a multi-byte whitespace character, and `I`. + let bytes: [u8; 3] = kani::any(); + let n: usize = kani::any(); + kani::assume(n <= 3); + for b in &bytes { + kani::assume(matches!( + *b, + b'0' | b'1' | b'9' | b'.' | b'e' | b'-' | b'+' | b' ' | b'x' | b'I' | 0xE2 | 0x80 + )); + } + let _ = string_to_number_bytes::<2>(&bytes[..n], &no_tables()); +} diff --git a/crates/clazel-js-number/tests/trim.rs b/crates/clazel-js-number/tests/trim.rs new file mode 100644 index 00000000..df2bc736 --- /dev/null +++ b/crates/clazel-js-number/tests/trim.rs @@ -0,0 +1,58 @@ +//! The byte-level `trim_str_whitespace` against `str::trim_matches` with +//! `is_str_whitespace`, for every Unicode scalar value at the start, at the +//! end, alone and doubled, and for the digit-radix helper's callers. + +use clazel_js_number::parse::{is_str_whitespace, string_to_number, trim_str_whitespace}; + +fn same(s: &str) { + let want = s.trim_matches(is_str_whitespace).as_bytes(); + assert_eq!(trim_str_whitespace(s.as_bytes()), want, "trim of {s:?}"); +} + +#[test] +fn trim_matches_str_trim_for_every_scalar() { + let step = if cfg!(miri) { 4099 } else { 1 }; + let mut cp: u32 = 0; + while cp <= 0x0010_FFFF { + if let Some(c) = char::from_u32(cp) { + same(&c.to_string()); + same(&format!("{c}{c}")); + same(&format!("{c}1")); + same(&format!("1{c}")); + same(&format!("{c}1{c}")); + same(&format!(" {c} 12.5{c}\t{c}")); + } + cp = cp.saturating_add(step); + } + same(""); + same("\u{2028}\u{2029}\u{FEFF}\u{A0}\u{3000}x\u{1680}\u{200A}"); +} + +#[test] +fn whitespace_set_is_what_the_spec_lists() { + for s in [ + "\u{9}7", + "\u{A}7", + "\u{B}7", + "\u{C}7", + "\u{D}7", + " 7", + "\u{A0}7", + "\u{1680}7", + "\u{2000}7", + "\u{200A}7", + "\u{2028}7", + "\u{2029}7", + "\u{202F}7", + "\u{205F}7", + "\u{3000}7", + "\u{FEFF}7", + "7\u{3000}", + ] { + assert!(string_to_number(s).to_bits() == 7f64.to_bits(), "{s:?}"); + } + // Not whitespace: ZWSP (U+200B), the Mongolian vowel separator, NEL. + for s in ["\u{200B}7", "\u{180E}7", "\u{85}7", "7\u{200B}"] { + assert!(string_to_number(s).is_nan(), "{s:?}"); + } +}