ironwork_numeric/
precision.rs

1//! Fixed-point intermediate results: how many integer and decimal places IBM carries for each
2//! operation, and exact arithmetic that drops exactly the digits it drops. See
3//! [`crate::assumptions::INTERMEDIATE_TABLE`].
4
5use crate::options::Arith;
6use std::fmt;
7use zarch::wide::U256;
8
9#[derive(Clone, Copy, Debug, PartialEq, Eq)]
10pub struct Places {
11    pub int: u32,
12    pub dec: u32,
13}
14
15impl Places {
16    pub const fn new(int: u32, dec: u32) -> Self {
17        Self { int, dec }
18    }
19
20    pub const fn total(self) -> u32 {
21        self.int + self.dec
22    }
23}
24
25pub fn sum_places(a: Places, b: Places) -> Places {
26    Places::new(a.int.max(b.int) + 1, a.dec.max(b.dec))
27}
28
29pub fn product_places(a: Places, b: Places) -> Places {
30    Places::new(a.int + b.int, a.dec + b.dec)
31}
32
33pub fn quotient_places(dividend: Places, divisor: Places, dmax: u32) -> Places {
34    Places::new(dividend.int + divisor.dec, dividend.dec.max(dmax))
35}
36
37/// The places carried for an intermediate result `ir`. `dmax` is the most decimal places among
38/// the statement's receivers and its operands other than divisors and exponents.
39pub fn carried(ir: Places, dmax: u32, arith: Arith) -> Places {
40    let n = arith.intermediate_digits();
41    if ir.total() <= n {
42        ir
43    } else if ir.dec <= dmax {
44        Places::new(n.saturating_sub(ir.dec), ir.dec)
45    } else if ir.int + dmax <= n {
46        Places::new(ir.int, n - ir.int)
47    } else {
48        Places::new(n.saturating_sub(dmax), dmax)
49    }
50}
51
52#[derive(Clone, Copy, Debug, PartialEq, Eq)]
53pub enum ArithError {
54    DivideByZero,
55    BeyondModel,
56}
57
58impl fmt::Display for ArithError {
59    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
60        match self {
61            Self::DivideByZero => write!(f, "division by zero"),
62            Self::BeyondModel => write!(f, "an intermediate wider than 256 bits"),
63        }
64    }
65}
66
67impl std::error::Error for ArithError {}
68
69/// A fixed-point value: magnitude × 10^-places.dec, with the places it is declared to hold.
70#[derive(Clone, Copy, Debug, PartialEq, Eq)]
71pub struct Fixed {
72    pub negative: bool,
73    pub magnitude: U256,
74    pub places: Places,
75}
76
77fn pow10(n: u32) -> U256 {
78    U256::pow10(n)
79}
80
81impl Fixed {
82    pub fn new(value: i128, places: Places) -> Self {
83        Self::signed(value < 0, U256::from_u128(value.unsigned_abs()), places)
84    }
85
86    fn signed(negative: bool, magnitude: U256, places: Places) -> Self {
87        Self { negative: negative && !magnitude.is_zero(), magnitude, places }
88    }
89
90    pub fn to_i128(self) -> Option<i128> {
91        zarch::wide::signed_i128(self.negative, self.magnitude)
92    }
93
94    /// Keeps `to.dec` decimal places, truncating the rest, and `to.int` integer places, dropping
95    /// high-order digits.
96    pub fn fit(self, to: Places) -> Self {
97        let from = self.places.dec;
98        let magnitude = if to.dec < from {
99            (self.magnitude.div_rem(pow10(from - to.dec)).0).div_rem(pow10(to.total())).1
100        } else {
101            self.magnitude.div_rem(pow10(to.int + from)).1.checked_mul(pow10(to.dec - from)).expect("fits by construction")
102        };
103        Self::signed(self.negative, magnitude, to)
104    }
105
106    fn aligned(self, dec: u32) -> Result<U256, ArithError> {
107        self.magnitude.checked_mul(pow10(dec - self.places.dec)).ok_or(ArithError::BeyondModel)
108    }
109
110    fn negated(self) -> Self {
111        Self::signed(!self.negative, self.magnitude, self.places)
112    }
113
114    pub fn add(self, other: Self, dmax: u32, arith: Arith) -> Result<Self, ArithError> {
115        let dec = self.places.dec.max(other.places.dec);
116        let (a, b) = (self.aligned(dec)?, other.aligned(dec)?);
117        let (negative, magnitude) = match (self.negative == other.negative, a >= b) {
118            (true, _) => (self.negative, a.checked_add(b).ok_or(ArithError::BeyondModel)?),
119            (false, true) => (self.negative, a - b),
120            (false, false) => (other.negative, b - a),
121        };
122        let ir = sum_places(self.places, other.places);
123        Ok(Self::signed(negative, magnitude, Places::new(ir.int, dec)).fit(carried(ir, dmax, arith)))
124    }
125
126    pub fn sub(self, other: Self, dmax: u32, arith: Arith) -> Result<Self, ArithError> {
127        self.add(other.negated(), dmax, arith)
128    }
129
130    pub fn mul(self, other: Self, dmax: u32, arith: Arith) -> Result<Self, ArithError> {
131        let ir = product_places(self.places, other.places);
132        let magnitude = self.magnitude.checked_mul(other.magnitude).ok_or(ArithError::BeyondModel)?;
133        Ok(Self::signed(self.negative != other.negative, magnitude, ir).fit(carried(ir, dmax, arith)))
134    }
135
136    pub fn div(self, divisor: Self, dmax: u32, arith: Arith) -> Result<Self, ArithError> {
137        if divisor.magnitude.is_zero() {
138            return Err(ArithError::DivideByZero);
139        }
140        let to = carried(quotient_places(self.places, divisor.places, dmax), dmax, arith);
141        let shift = (divisor.places.dec + to.dec) as i64 - self.places.dec as i64;
142        let (numerator, denominator) = if shift >= 0 {
143            (self.magnitude.checked_mul(pow10(shift as u32)), Some(divisor.magnitude))
144        } else {
145            (Some(self.magnitude), divisor.magnitude.checked_mul(pow10(shift.unsigned_abs() as u32)))
146        };
147        let (numerator, denominator) = (numerator.ok_or(ArithError::BeyondModel)?, denominator.ok_or(ArithError::BeyondModel)?);
148        let quotient = numerator.div_rem(denominator).0;
149        let exact = Self::signed(self.negative != divisor.negative, quotient, Places::new(u32::MAX / 2, to.dec));
150        Ok(exact.fit(to))
151    }
152
153    /// The value a receiver of `places` gets: truncated, or rounded half away from zero, and whether
154    /// the integer part overflowed it (ON SIZE ERROR).
155    pub fn to_receiver(self, places: Places, rounded: bool) -> (Self, bool) {
156        let from = self.places.dec;
157        let magnitude = if places.dec >= from {
158            self.magnitude.checked_mul(pow10(places.dec - from))
159        } else {
160            let (kept, dropped) = self.magnitude.div_rem(pow10(from - places.dec));
161            let half = pow10(from - places.dec - 1).checked_mul(U256::from_u128(5)).unwrap();
162            Some(if rounded && dropped >= half { kept + U256::from_u128(1) } else { kept })
163        };
164        let cap = pow10(places.total());
165        match magnitude {
166            Some(m) if m < cap => (Self::signed(self.negative, m, places), false),
167            Some(m) => (Self::signed(self.negative, m.div_rem(cap).1, places), true),
168            None => (Self::signed(self.negative, U256::ZERO, places), true),
169        }
170    }
171}
172
173#[cfg(test)]
174mod tests {
175    use super::*;
176
177    const S18: Places = Places::new(18, 0);
178
179    #[test]
180    fn places_for_each_operation() {
181        assert_eq!(sum_places(Places::new(5, 2), Places::new(3, 4)), Places::new(6, 4));
182        assert_eq!(product_places(Places::new(5, 2), Places::new(3, 4)), Places::new(8, 6));
183        assert_eq!(quotient_places(Places::new(5, 2), Places::new(3, 4), 3), Places::new(9, 3));
184    }
185
186    #[test]
187    fn the_carried_places_table() {
188        assert_eq!(carried(Places::new(20, 5), 5, Arith::Compat), Places::new(20, 5));
189        assert_eq!(carried(Places::new(28, 6), 6, Arith::Compat), Places::new(24, 6));
190        assert_eq!(carried(Places::new(20, 12), 4, Arith::Compat), Places::new(20, 10));
191        assert_eq!(carried(Places::new(28, 12), 4, Arith::Compat), Places::new(26, 4));
192        assert_eq!(carried(Places::new(28, 6), 6, Arith::Extend), Places::new(25, 6));
193    }
194
195    #[test]
196    fn an_18_by_18_digit_product_loses_high_order_digits_under_compat_but_fewer_under_extend() {
197        let big = Fixed::new(999_999_999_999_999_999, S18);
198        let compat = big.mul(big, 0, Arith::Compat).unwrap();
199        let extend = big.mul(big, 0, Arith::Extend).unwrap();
200        assert_eq!(compat.places, Places::new(30, 0));
201        assert_eq!(extend.places, Places::new(31, 0));
202        let exact = U256::widening_mul(999_999_999_999_999_999, 999_999_999_999_999_999);
203        assert_eq!(compat.magnitude, exact.div_rem(U256::pow10(30)).1);
204        assert_eq!(extend.magnitude, exact.div_rem(U256::pow10(31)).1);
205    }
206
207    #[test]
208    fn division_carries_dmax_decimal_places_and_truncates() {
209        let q = Fixed::new(10, Places::new(2, 0)).div(Fixed::new(3, Places::new(1, 0)), 2, Arith::Compat).unwrap();
210        assert_eq!((q.to_i128(), q.places.dec), (Some(333), 2));
211        let n = Fixed::new(-10, Places::new(2, 0)).div(Fixed::new(3, Places::new(1, 0)), 2, Arith::Compat).unwrap();
212        assert_eq!(n.to_i128(), Some(-333));
213        assert_eq!(Fixed::new(1, S18).div(Fixed::new(0, S18), 0, Arith::Compat), Err(ArithError::DivideByZero));
214    }
215
216    #[test]
217    fn addition_aligns_decimal_points() {
218        let s = Fixed::new(125, Places::new(1, 2)).add(Fixed::new(-3, Places::new(1, 0)), 2, Arith::Compat).unwrap();
219        assert_eq!((s.to_i128(), s.places), (Some(-175), Places::new(2, 2)));
220    }
221
222    #[test]
223    fn receivers_truncate_or_round_half_away_and_flag_size_errors() {
224        let v = Fixed::new(-12345, Places::new(3, 2));
225        assert_eq!(v.to_receiver(Places::new(3, 1), false).0.to_i128(), Some(-1234));
226        assert_eq!(v.to_receiver(Places::new(3, 1), true).0.to_i128(), Some(-1235));
227        let (wrapped, size_error) = v.to_receiver(Places::new(2, 0), false);
228        assert_eq!((wrapped.to_i128(), size_error), (Some(-23), true));
229        let (rounded_over, size_error) = Fixed::new(999, Places::new(1, 2)).to_receiver(Places::new(1, 1), true);
230        assert_eq!((rounded_over.to_i128(), size_error), (Some(0), true));
231    }
232
233    #[test]
234    fn negative_zero_is_normalized() {
235        let z = Fixed::new(5, Places::new(1, 0)).sub(Fixed::new(5, Places::new(1, 0)), 0, Arith::Compat).unwrap();
236        assert!(!z.negative);
237    }
238}
ironwork_numeric/precision.rs

ironwork_numeric/
precision.rs
