iceberg/spec/values/
decimal_utils.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Compatibility layer for decimal operations.
19//!
20//! Provides rust_decimal-compatible API using fastnum's D128 internally.
21//! D128 supports 38-digit precision, meeting the Iceberg spec requirement.
22
23use fastnum::D128;
24use fastnum::decimal::Context;
25
26use crate::{Error, ErrorKind, Result};
27
28/// Re-export D128 as the Decimal type for use throughout the crate.
29pub type Decimal = D128;
30
31/// Create a D128 from mantissa (i128) and scale (u32).
32///
33/// This is equivalent to rust_decimal's `Decimal::from_i128_with_scale`.
34/// The value is computed as: mantissa * 10^(-scale)
35///
36/// For example:
37/// - mantissa=12345, scale=2 => 123.45
38/// - mantissa=-456, scale=3 => -0.456
39pub fn decimal_from_i128_with_scale(mantissa: i128, scale: u32) -> Decimal {
40    if scale == 0 {
41        return D128::from_i128(mantissa).expect("i128 always fits in D128");
42    }
43
44    // Convert mantissa to string and insert decimal point at the right position
45    let is_negative = mantissa < 0;
46    let abs_str = mantissa.unsigned_abs().to_string();
47    let scale_usize = scale as usize;
48
49    let decimal_str = if abs_str.len() <= scale_usize {
50        // Need leading zeros: e.g., mantissa=456, scale=3 => "0.456"
51        // Or mantissa=5, scale=3 => "0.005"
52        let zeros_needed = scale_usize - abs_str.len();
53        format!(
54            "{}0.{}{}",
55            if is_negative { "-" } else { "" },
56            "0".repeat(zeros_needed),
57            abs_str
58        )
59    } else {
60        // Insert decimal point: e.g., mantissa=12345, scale=2 => "123.45"
61        let decimal_pos = abs_str.len() - scale_usize;
62        format!(
63            "{}{}.{}",
64            if is_negative { "-" } else { "" },
65            &abs_str[..decimal_pos],
66            &abs_str[decimal_pos..]
67        )
68    };
69
70    D128::from_str(&decimal_str, Context::default())
71        .expect("constructed decimal string is always valid")
72}
73
74/// Try to create a D128 from mantissa and scale, with validation.
75///
76/// This is equivalent to rust_decimal's `Decimal::try_from_i128_with_scale`.
77/// Currently always succeeds for 38-digit decimals.
78pub fn try_decimal_from_i128_with_scale(mantissa: i128, scale: u32) -> Result<Decimal> {
79    // For now, always succeeds since D128 supports full 38-digit precision
80    Ok(decimal_from_i128_with_scale(mantissa, scale))
81}
82
83/// Create a D128 from i64 mantissa and scale.
84///
85/// This is equivalent to rust_decimal's `Decimal::new`.
86#[allow(dead_code)]
87pub fn decimal_new(mantissa: i64, scale: u32) -> Decimal {
88    decimal_from_i128_with_scale(mantissa as i128, scale)
89}
90
91/// Parse a decimal from string with exact representation.
92///
93/// This is equivalent to rust_decimal's `Decimal::from_str_exact`.
94pub fn decimal_from_str_exact(s: &str) -> Result<Decimal> {
95    D128::from_str(s, Context::default())
96        .map_err(|e| Error::new(ErrorKind::DataInvalid, format!("Can't parse decimal: {e}")))
97}
98
99/// Get the mantissa (unscaled coefficient) as i128.
100///
101/// This is equivalent to rust_decimal's `decimal.mantissa()`.
102///
103/// The mantissa is signed: negative decimals return negative mantissa.
104pub fn decimal_mantissa(d: &Decimal) -> i128 {
105    // digits() returns unsigned coefficient as UInt<N>
106    // For Iceberg decimals (max 38 digits), this always fits in u128/i128
107    let digits = d.digits();
108
109    // Convert UInt<2> to u128 - this always succeeds for Iceberg-compliant decimals
110    // since 38 digits requires ~127 bits and u128 has 128 bits
111    let unsigned: u128 = digits
112        .to_u128()
113        .expect("Iceberg decimals (max 38 digits) always fit in u128");
114
115    let signed = unsigned as i128;
116    if d.is_sign_negative() {
117        -signed
118    } else {
119        signed
120    }
121}
122
123/// Get the decimal digit precision of a mantissa.
124///
125/// A mantissa of 0 has a precision of 1.
126pub fn decimal_precision(mantissa: i128) -> u32 {
127    mantissa
128        .unsigned_abs()
129        .checked_ilog10()
130        .map_or(1, |x| x + 1)
131}
132
133/// Get the scale (number of digits after decimal point).
134///
135/// This is equivalent to rust_decimal's `decimal.scale()`.
136pub fn decimal_scale(d: &Decimal) -> u32 {
137    let frac = d.fractional_digits_count();
138    if frac < 0 { 0 } else { frac as u32 }
139}
140
141/// Rescale a decimal to the given scale, returning the rescaled value.
142///
143/// This is equivalent to rust_decimal's `decimal.rescale(scale)`.
144pub fn decimal_rescale(d: Decimal, scale: u32) -> Decimal {
145    d.rescale(scale as i16)
146}
147
148/// Convert big-endian signed bytes to i128.
149///
150/// This handles variable-length byte arrays (up to 16 bytes) with sign extension.
151/// Returns None if the byte array is longer than 16 bytes.
152pub fn i128_from_be_bytes(bytes: &[u8]) -> Option<i128> {
153    if bytes.is_empty() {
154        return Some(0);
155    }
156    if bytes.len() > 16 {
157        return None; // Too large for i128
158    }
159
160    // Check sign bit (most significant bit of first byte)
161    let is_negative = bytes[0] & 0x80 != 0;
162
163    // Pad to 16 bytes with sign extension
164    let mut padded = if is_negative { [0xFF; 16] } else { [0; 16] };
165    let start = 16 - bytes.len();
166    padded[start..].copy_from_slice(bytes);
167
168    Some(i128::from_be_bytes(padded))
169}
170
171/// Convert i128 to big-endian signed bytes with minimum length.
172///
173/// This produces the shortest two's complement representation of the value.
174/// The result is suitable for Iceberg decimal binary serialization.
175pub fn i128_to_be_bytes_min(value: i128) -> Vec<u8> {
176    let bytes = value.to_be_bytes();
177
178    // Find the first significant byte
179    // For positive numbers, skip leading 0x00 bytes (but keep sign bit)
180    // For negative numbers, skip leading 0xFF bytes (but keep sign bit)
181    let is_negative = value < 0;
182    let skip_byte = if is_negative { 0xFF } else { 0x00 };
183
184    let mut start = 0;
185    while start < 15 && bytes[start] == skip_byte {
186        // Check if the next byte has the correct sign bit
187        let next_byte = bytes[start + 1];
188        let next_is_negative = (next_byte & 0x80) != 0;
189        if next_is_negative == is_negative {
190            start += 1;
191        } else {
192            break;
193        }
194    }
195
196    bytes[start..].to_vec()
197}
198
199#[cfg(test)]
200mod tests {
201    use super::*;
202
203    #[test]
204    fn test_decimal_from_i128_with_scale() {
205        let d = decimal_from_i128_with_scale(12345, 2);
206        assert_eq!(d.to_string(), "123.45");
207
208        let d = decimal_from_i128_with_scale(-12345, 2);
209        assert_eq!(d.to_string(), "-123.45");
210
211        let d = decimal_from_i128_with_scale(0, 5);
212        assert_eq!(d.to_string(), "0.00000");
213    }
214
215    #[test]
216    fn test_decimal_new() {
217        let d = decimal_new(123, 2);
218        assert_eq!(d.to_string(), "1.23");
219
220        let d = decimal_new(-456, 3);
221        assert_eq!(d.to_string(), "-0.456");
222    }
223
224    #[test]
225    fn test_decimal_from_str_exact() {
226        let d = decimal_from_str_exact("123.45").unwrap();
227        assert_eq!(d.to_string(), "123.45");
228
229        let d = decimal_from_str_exact("-0.001").unwrap();
230        assert_eq!(d.to_string(), "-0.001");
231
232        let d = decimal_from_str_exact("99999999999999999999999999999999999999").unwrap();
233        assert_eq!(d.to_string(), "99999999999999999999999999999999999999");
234    }
235
236    #[test]
237    fn test_decimal_mantissa() {
238        let d = decimal_from_i128_with_scale(12345, 2);
239        assert_eq!(decimal_mantissa(&d), 12345);
240
241        let d = decimal_from_i128_with_scale(-12345, 2);
242        assert_eq!(decimal_mantissa(&d), -12345);
243    }
244
245    #[test]
246    fn test_decimal_precision() {
247        assert_eq!(decimal_precision(0), 1);
248        assert_eq!(decimal_precision(5), 1);
249        assert_eq!(decimal_precision(42), 2);
250        assert_eq!(decimal_precision(-42), 2);
251        // power-of-10 boundaries, where off-by-one bugs in log10 logic live
252        assert_eq!(decimal_precision(9), 1);
253        assert_eq!(decimal_precision(10), 2);
254        assert_eq!(decimal_precision(99), 2);
255        assert_eq!(decimal_precision(100), 3);
256
257        // max Iceberg decimal precision
258        assert_eq!(
259            decimal_precision(99999999999999999999999999999999999999),
260            38
261        );
262        assert_eq!(
263            decimal_precision(-99999999999999999999999999999999999999),
264            38
265        );
266
267        // i128 extremes
268        assert_eq!(decimal_precision(i128::MAX), 39);
269        assert_eq!(decimal_precision(i128::MIN), 39);
270    }
271
272    #[test]
273    fn test_decimal_scale() {
274        let d = decimal_from_i128_with_scale(12345, 2);
275        assert_eq!(decimal_scale(&d), 2);
276
277        let d = decimal_from_i128_with_scale(12345, 0);
278        assert_eq!(decimal_scale(&d), 0);
279    }
280
281    #[test]
282    fn test_decimal_rescale() {
283        let d = decimal_from_str_exact("123.45").unwrap();
284        let rescaled = decimal_rescale(d, 4);
285        assert_eq!(decimal_scale(&rescaled), 4);
286        assert_eq!(decimal_mantissa(&rescaled), 1234500);
287    }
288
289    #[test]
290    fn test_38_digit_precision() {
291        // Test that we can handle 38-digit decimals (Iceberg spec requirement)
292        let max_38_digits = "99999999999999999999999999999999999999";
293        let d = decimal_from_str_exact(max_38_digits).unwrap();
294        assert_eq!(d.to_string(), max_38_digits);
295
296        let min_38_digits = "-99999999999999999999999999999999999999";
297        let d = decimal_from_str_exact(min_38_digits).unwrap();
298        assert_eq!(d.to_string(), min_38_digits);
299    }
300
301    #[test]
302    fn test_i128_from_be_bytes() {
303        // Empty bytes
304        assert_eq!(i128_from_be_bytes(&[]), Some(0));
305
306        // Positive values
307        assert_eq!(i128_from_be_bytes(&[0x01]), Some(1));
308        assert_eq!(i128_from_be_bytes(&[0x7F]), Some(127));
309        assert_eq!(i128_from_be_bytes(&[0x00, 0xFF]), Some(255));
310        assert_eq!(i128_from_be_bytes(&[0x04, 0xD2]), Some(1234));
311
312        // Negative values (sign extension)
313        assert_eq!(i128_from_be_bytes(&[0xFF]), Some(-1));
314        assert_eq!(i128_from_be_bytes(&[0x80]), Some(-128));
315        assert_eq!(i128_from_be_bytes(&[0xFB, 0x2E]), Some(-1234));
316
317        // Too large (> 16 bytes)
318        assert_eq!(i128_from_be_bytes(&[0; 17]), None);
319    }
320
321    #[test]
322    fn test_i128_to_be_bytes_min() {
323        // Positive values
324        assert_eq!(i128_to_be_bytes_min(0), vec![0x00]);
325        assert_eq!(i128_to_be_bytes_min(1), vec![0x01]);
326        assert_eq!(i128_to_be_bytes_min(127), vec![0x7F]);
327        assert_eq!(i128_to_be_bytes_min(128), vec![0x00, 0x80]);
328        assert_eq!(i128_to_be_bytes_min(255), vec![0x00, 0xFF]);
329        assert_eq!(i128_to_be_bytes_min(1234), vec![0x04, 0xD2]);
330
331        // Negative values
332        assert_eq!(i128_to_be_bytes_min(-1), vec![0xFF]);
333        assert_eq!(i128_to_be_bytes_min(-128), vec![0x80]);
334        assert_eq!(i128_to_be_bytes_min(-129), vec![0xFF, 0x7F]);
335        assert_eq!(i128_to_be_bytes_min(-1234), vec![0xFB, 0x2E]);
336
337        // Round trip test
338        for val in [
339            0i128,
340            1,
341            -1,
342            127,
343            -128,
344            255,
345            -256,
346            12345,
347            -12345,
348            i128::MAX,
349            i128::MIN,
350        ] {
351            let bytes = i128_to_be_bytes_min(val);
352            assert_eq!(
353                i128_from_be_bytes(&bytes),
354                Some(val),
355                "Round trip failed for {val}"
356            );
357        }
358    }
359}
iceberg/spec/values/decimal_utils.rs

iceberg/spec/values/
decimal_utils.rs
