Skip to main content

vortex_array/arrays/decimal/
utils.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use itertools::Itertools;
5use itertools::MinMaxResult;
6use vortex_buffer::Buffer;
7use vortex_buffer::BufferMut;
8use vortex_compute::lane_kernels::IndexedSourceExt;
9use vortex_error::VortexExpect;
10use vortex_error::VortexResult;
11use vortex_error::vortex_bail;
12use vortex_error::vortex_ensure_eq;
13use vortex_mask::AllOr;
14use vortex_mask::Mask;
15
16pub use crate::aggregate_fn::fns::min_max::valid_range;
17use crate::arrays::DecimalArray;
18use crate::arrays::decimal::DecimalArrayExt;
19use crate::buffer::BufferHandle;
20use crate::dtype::BigCast;
21use crate::dtype::DecimalDType;
22use crate::dtype::DecimalType;
23use crate::dtype::NativeDecimalType;
24use crate::dtype::i256;
25use crate::match_each_decimal_value_type;
26
27/// Return the array's unscaled values widened to `W`, which must be at least as wide as the
28/// array's storage type.
29pub(crate) fn widened_buffer<W: NativeDecimalType>(array: &DecimalArray) -> Buffer<W> {
30    if array.values_type() == W::DECIMAL_TYPE {
31        return array.buffer::<W>();
32    }
33    match_each_decimal_value_type!(array.values_type(), |T| {
34        // Only storage types narrower than `W` reach here. The const condition lets the compiler
35        // skip codegen of the other arms.
36        if const { (T::DECIMAL_TYPE as u8) < (W::DECIMAL_TYPE as u8) } {
37            widen_values::<T, W>(&array.buffer::<T>())
38        } else {
39            unreachable!(
40                "{} is not narrower than {}",
41                T::DECIMAL_TYPE,
42                W::DECIMAL_TYPE
43            )
44        }
45    })
46}
47
48/// Return the array's unscaled values converted to exactly `W`, whatever the array's
49/// storage type. Zero-copy when the array is already stored at `W`.
50///
51/// Widening is lossless. Narrowing fails for any *valid* value that does not fit `W`.
52/// Null slots may hold arbitrary bytes and never fail; their contents in the returned
53/// buffer are likewise arbitrary and must not be read.
54pub fn converted_buffer<W: NativeDecimalType>(
55    array: &DecimalArray,
56    validity: &Mask,
57) -> VortexResult<Buffer<W>> {
58    // Widening can never fail, so it needs no validation pass.
59    if array.values_type() <= W::DECIMAL_TYPE {
60        return Ok(widened_buffer(array));
61    }
62    match_each_decimal_value_type!(array.values_type(), |T| {
63        // Only storage types wider than `W` reach here. The const condition lets the compiler
64        // skip codegen of the other arms.
65        if const { (T::DECIMAL_TYPE as u8) > (W::DECIMAL_TYPE as u8) } {
66            let src = array.buffer::<T>();
67            match validity {
68                Mask::AllTrue(_) => {
69                    // Keeping the overflow scan branchless and vectorizable. Only on overflow
70                    // do we rescan for diagnostics.
71                    let any_overflow = src.iter().fold(false, |acc, v| acc | W::from(*v).is_none());
72                    if any_overflow {
73                        let (i, v) = src
74                            .iter()
75                            .enumerate()
76                            .find(|&(_, v)| W::from(*v).is_none())
77                            .vortex_expect("overflow scan found an overflowing value");
78                        vortex_bail!(
79                            "decimal value {v} at index {i} does not fit {}",
80                            W::DECIMAL_TYPE
81                        );
82                    }
83                }
84                Mask::AllFalse(_) => return Ok(Buffer::zeroed(src.len())),
85                Mask::Values(values) => {
86                    let any_overflow = src.iter().fold(false, |acc, v| acc | W::from(*v).is_none());
87                    if any_overflow {
88                        for (i, v) in src.iter().enumerate() {
89                            if values.value(i) && W::from(*v).is_none() {
90                                vortex_bail!(
91                                    "decimal value {v} at index {i} does not fit {}",
92                                    W::DECIMAL_TYPE
93                                );
94                            }
95                        }
96                    }
97                }
98            }
99            // The convert pass is infallible: every valid value fits, and out-of-range null-slot
100            // garbage is mapped to the default value. Callers must still ignore null slots.
101            Ok(src
102                .iter()
103                .map(|v| W::from(*v).unwrap_or_default())
104                .collect())
105        } else {
106            unreachable!("{} is not wider than {}", T::DECIMAL_TYPE, W::DECIMAL_TYPE)
107        }
108    })
109}
110
111/// Copies unscaled decimal values into a new buffer at the canonical width of `target`.
112///
113/// The copy holds `values.len()` values of [`DecimalDType::canonical_values_type`]. It never
114/// rescales, so the values keep the scale of the source.
115///
116/// - A narrowing copy, where the canonical width is narrower than `F`, checks every valid value
117///   against the precision of `target` with [`check_precision`]. A value that fits the width but
118///   not the precision fails too. Null slots of the copy hold zeros.
119/// - A widening or same-width copy checks nothing and keeps the null slots. The caller **must**
120///   know that every valid value fits `target`, for example because `target` has at least the
121///   precision of the source dtype. Otherwise the copy holds values outside the precision, which
122///   is an incorrect result but not undefined behavior. A caller that owns a buffer that already
123///   has the canonical width can keep it and call [`check_precision`] instead.
124///
125/// # Errors
126///
127/// Returns an error if `validity` and `values` have different lengths, or if a narrowing copy
128/// finds a valid value outside the precision of `target`, as [`check_precision`] describes.
129pub fn copy_to_canonical_width<F: NativeDecimalType>(
130    values: &[F],
131    validity: &Mask,
132    target: DecimalDType,
133) -> VortexResult<BufferHandle> {
134    vortex_ensure_eq!(validity.len(), values.len());
135
136    let canonical_type = target.canonical_values_type();
137    if F::DECIMAL_TYPE == canonical_type {
138        return Ok(BufferHandle::new_host(
139            Buffer::<F>::copy_from(values).into_byte_buffer(),
140        ));
141    }
142
143    let copy = match_each_decimal_value_type!(canonical_type, |W| {
144        if const { (F::DECIMAL_TYPE as u8) <= (W::DECIMAL_TYPE as u8) } {
145            widen_values::<F, W>(values).into_byte_buffer()
146        } else {
147            check_precision(values, validity, target)?;
148            narrow_checked_values::<F, W>(values, validity).into_byte_buffer()
149        }
150    });
151
152    Ok(BufferHandle::new_host(copy))
153}
154
155/// Widens every value to `W`, which **must** be at least as wide as `F`, or this panics. Null slots
156/// keep their values.
157fn widen_values<F: NativeDecimalType, W: NativeDecimalType>(values: &[F]) -> Buffer<W> {
158    // This cannot be a `const` assert: the disabled `if const` branches of `widened_buffer` and
159    // `copy_to_canonical_width` still name narrower pairs, and rustc evaluates the inline constants
160    // of every function they name. Both sides are constants, so the check folds away.
161    assert!(
162        (F::DECIMAL_TYPE as u8) <= (W::DECIMAL_TYPE as u8),
163        "widen_values requires a target at least as wide as the source, got {} into {}",
164        F::DECIMAL_TYPE,
165        W::DECIMAL_TYPE
166    );
167
168    // NB: Keep the `unwrap_or_default` fallback and `from_trusted_len_iter`. The fallback is dead
169    // because `W` is at least as wide as `F`, so the write loop has one exit and no panic edge. A
170    // `collect` writes through `BufferMut::extend_iter`, whose loop also exits when the reserved
171    // capacity runs out, and the LLVM loop vectorizer leaves some pairs scalar there, such as `i64`
172    // to `i128`. The accepted trade-off is that this loop is slower than `collect` when `W` is
173    // `i256`, for an unknown reason. The `copy_to_canonical_width` benchmark covers these pairs.
174    Buffer::from_trusted_len_iter(
175        values
176            .iter()
177            .map(|&value| <W as BigCast>::from(value).unwrap_or_default()),
178    )
179}
180
181/// Narrows values that [`check_precision`] accepted to `W`, and writes zeros into the null slots.
182fn narrow_checked_values<F: NativeDecimalType, W: NativeDecimalType>(
183    values: &[F],
184    validity: &Mask,
185) -> Buffer<W> {
186    let len = values.len();
187    let valid_bits = match validity.bit_buffer() {
188        AllOr::All => None,
189        AllOr::None => return Buffer::zeroed(len),
190        AllOr::Some(valid_bits) => Some(valid_bits),
191    };
192
193    // NB: a null slot can hold a value that does not fit `W`, so the map must not fail on it.
194    // `map_masked_into` then overwrites every null slot with zero.
195    let narrow = |value: F| <W as BigCast>::from(value).unwrap_or_default();
196
197    let mut buffer = BufferMut::<W>::with_capacity(len);
198    let out = &mut buffer.spare_capacity_mut()[..len];
199    match valid_bits {
200        None => values.map_into(out, narrow),
201        Some(valid_bits) => values.map_masked_into(valid_bits, out, narrow),
202    }
203
204    // SAFETY: `map_into` and `map_masked_into` write every lane of `out`.
205    unsafe { buffer.set_len(len) };
206
207    buffer.freeze()
208}
209
210/// Checks that every valid value fits the precision of `decimal_dtype`.
211///
212/// Null slots are not checked, so they can hold any value. The check takes a materialized
213/// [`Mask`], so it needs no execution context.
214///
215/// # Errors
216///
217/// Returns an error if `validity` and `values` have different lengths, or if a valid value is
218/// outside the precision of `decimal_dtype`. The error names the first such row, its value and
219/// `decimal_dtype`.
220pub fn check_precision<T: NativeDecimalType>(
221    values: &[T],
222    validity: &Mask,
223    decimal_dtype: DecimalDType,
224) -> VortexResult<()> {
225    vortex_ensure_eq!(validity.len(), values.len());
226
227    // The bound tables stop at `T::MAX_PRECISION`. Every value of `T` has at most
228    // `T::MAX_PRECISION + 1` digits, so a larger precision holds every value of `T`.
229    let precision = decimal_dtype.precision();
230    if precision > T::MAX_PRECISION {
231        return Ok(());
232    }
233    let min = T::MIN_BY_PRECISION[usize::from(precision)];
234    let max = T::MAX_BY_PRECISION[usize::from(precision)];
235    let is_outside = |value: T| (value < min) | (value > max);
236
237    let valid_bits = match validity.bit_buffer() {
238        AllOr::All => None,
239        AllOr::None => return Ok(()),
240        AllOr::Some(valid_bits) => Some(valid_bits),
241    };
242
243    // The fold is branchless so that it vectorizes. It also reads the null slots, so a hit only
244    // means that the rescan below must look for a valid row outside the precision.
245    let any_outside = values
246        .iter()
247        .fold(false, |acc, &value| acc | is_outside(value));
248    if !any_outside {
249        return Ok(());
250    }
251
252    let first_outside = match valid_bits {
253        None => values.iter().position(|&value| is_outside(value)),
254        Some(valid_bits) => valid_bits
255            .set_indices()
256            .find(|&row| is_outside(values[row])),
257    };
258    if let Some(row) = first_outside {
259        vortex_bail!(
260            "decimal value at row {row} must be within the precision of {decimal_dtype}, got {}",
261            values[row]
262        );
263    }
264
265    Ok(())
266}
267
268macro_rules! try_downcast {
269    ($array:expr, from: $src:ty, to: $($dst:ty),*) => {{
270        // Collect the min/max of the values
271        let minmax = $array.buffer::<$src>().iter().copied().minmax();
272        match minmax {
273            MinMaxResult::NoElements => return $array,
274            MinMaxResult::OneElement(_) => return $array,
275            MinMaxResult::MinMax(min, max) => {
276                $(
277                    if <$dst as BigCast>::from(min).is_some() && <$dst as BigCast>::from(max).is_some() {
278                        return DecimalArray::new::<$dst>(
279                            $array
280                                .buffer::<$src>()
281                                .into_iter()
282                                .map(|v| <$dst as BigCast>::from(v).vortex_expect("decimal conversion failure"))
283                                .collect(),
284                            $array.decimal_dtype(),
285                            $array
286                                .validity()
287                                .vortex_expect("decimal validity should be derivable"),
288                        );
289                    }
290                )*
291
292                return $array;
293            }
294        }
295    }};
296}
297
298/// Attempt to narrow the decimal array to any smaller supported type.
299pub fn narrowed_decimal(decimal_array: DecimalArray) -> DecimalArray {
300    match decimal_array.values_type() {
301        // Cannot narrow any more
302        DecimalType::I8 => decimal_array,
303        DecimalType::I16 => {
304            try_downcast!(decimal_array, from: i16, to: i8)
305        }
306        DecimalType::I32 => {
307            try_downcast!(decimal_array, from: i32, to: i8, i16)
308        }
309        DecimalType::I64 => {
310            try_downcast!(decimal_array, from: i64, to: i8, i16, i32)
311        }
312        DecimalType::I128 => {
313            try_downcast!(decimal_array, from: i128, to: i8, i16, i32, i64)
314        }
315        DecimalType::I256 => {
316            try_downcast!(decimal_array, from: i256, to: i8, i16, i32, i64, i128)
317        }
318    }
319}
320
321#[cfg(test)]
322mod tests {
323    use rstest::rstest;
324    use vortex_buffer::Buffer;
325    use vortex_error::VortexExpect;
326    use vortex_error::VortexResult;
327    use vortex_mask::Mask;
328
329    use super::check_precision;
330    use super::converted_buffer;
331    use super::copy_to_canonical_width;
332    use super::valid_range;
333    use super::widen_values;
334    use crate::arrays::DecimalArray;
335    use crate::dtype::BigCast;
336    use crate::dtype::DecimalDType;
337    use crate::dtype::DecimalType;
338    use crate::dtype::NativeDecimalType;
339    use crate::dtype::ToI256;
340    use crate::dtype::i256;
341    use crate::match_each_decimal_value_type;
342    use crate::validity::Validity;
343
344    /// Runs [`copy_to_canonical_width`], checks that the copy has the canonical width of `target`,
345    /// and reads the copy back as `i256`.
346    fn copy_as_i256<F: NativeDecimalType>(
347        values: &[F],
348        validity: &Mask,
349        target: DecimalDType,
350    ) -> VortexResult<Vec<i256>> {
351        let copy = copy_to_canonical_width(values, validity, target)?;
352        let width = target.canonical_values_type();
353        assert_eq!(copy.len(), values.len() * width.byte_width());
354
355        Ok(match_each_decimal_value_type!(width, |W| {
356            Buffer::<W>::from_byte_buffer(copy.unwrap_host())
357                .iter()
358                .map(|value| value.to_i256().vortex_expect("decimal values fit i256"))
359                .collect()
360        }))
361    }
362
363    /// Returns `10^precision`, the smallest magnitude outside `precision`.
364    fn ten_to_the(precision: u8) -> i256 {
365        i256::from_i128(10)
366            .checked_pow(precision.into())
367            .vortex_expect("10^76 fits i256")
368    }
369
370    /// Converts each test value to the native type `T`.
371    fn to_native<T: NativeDecimalType>(values: &[i256]) -> Vec<T> {
372        values
373            .iter()
374            .map(|&value| <T as BigCast>::from(value).vortex_expect("test value fits the type"))
375            .collect()
376    }
377
378    #[rstest]
379    #[case::all_valid(vec![5, -3, 7], vec![true, true, true], Some((-3, 7)))]
380    #[case::partly_valid(vec![5, -3, 7], vec![true, true, false], Some((-3, 5)))]
381    #[case::all_null(vec![5, -3, 7], vec![false, false, false], None)]
382    #[case::empty(vec![], vec![], None)]
383    #[case::one_valid(vec![5, -3, 7], vec![false, true, false], Some((-3, -3)))]
384    #[case::outside_i8_precision(vec![-100, 100], vec![true, true], Some((-100, 100)))]
385    fn test_valid_range(
386        #[case] values: Vec<i8>,
387        #[case] validity: Vec<bool>,
388        #[case] expected: Option<(i8, i8)>,
389        #[values(
390            DecimalType::I8,
391            DecimalType::I16,
392            DecimalType::I32,
393            DecimalType::I64,
394            DecimalType::I128,
395            DecimalType::I256
396        )]
397        storage: DecimalType,
398    ) -> VortexResult<()> {
399        let validity = Mask::from_iter(validity);
400        match_each_decimal_value_type!(storage, |T| {
401            let values: Vec<T> = values
402                .iter()
403                .map(|&value| {
404                    <T as BigCast>::from(value).vortex_expect("i8 values fit every decimal type")
405                })
406                .collect();
407            let expected = expected.map(|(min, max)| {
408                (
409                    <T as BigCast>::from(min).vortex_expect("i8 values fit every decimal type"),
410                    <T as BigCast>::from(max).vortex_expect("i8 values fit every decimal type"),
411                )
412            });
413            assert_eq!(valid_range(&values, &validity), expected);
414        });
415
416        Ok(())
417    }
418
419    #[rstest]
420    fn test_valid_range_ignores_null_extremes(
421        #[values(
422            DecimalType::I8,
423            DecimalType::I16,
424            DecimalType::I32,
425            DecimalType::I64,
426            DecimalType::I128,
427            DecimalType::I256
428        )]
429        storage: DecimalType,
430    ) -> VortexResult<()> {
431        let validity = Mask::from_iter([false, true, true, false]);
432        match_each_decimal_value_type!(storage, |T| {
433            let min = <T as BigCast>::from(-3i8).vortex_expect("-3 fits every decimal type");
434            let max = <T as BigCast>::from(7i8).vortex_expect("7 fits every decimal type");
435            assert_eq!(
436                valid_range(&[T::MIN, min, max, T::MAX], &validity),
437                Some((min, max))
438            );
439            assert_eq!(
440                valid_range(&[T::MIN, T::MAX], &Mask::AllTrue(2)),
441                Some((T::MIN, T::MAX))
442            );
443        });
444
445        Ok(())
446    }
447
448    #[test]
449    #[should_panic(expected = "valid_range requires one validity bit per value")]
450    fn test_valid_range_rejects_mismatched_mask() {
451        valid_range(&[1i8, 2], &Mask::AllTrue(3));
452    }
453
454    /// Each pair selects a different widening or narrowing conversion.
455    #[rstest]
456    fn converted_buffer_every_storage_pair(
457        #[values(
458            DecimalType::I8,
459            DecimalType::I16,
460            DecimalType::I32,
461            DecimalType::I64,
462            DecimalType::I128,
463            DecimalType::I256
464        )]
465        storage: DecimalType,
466        #[values(
467            DecimalType::I8,
468            DecimalType::I16,
469            DecimalType::I32,
470            DecimalType::I64,
471            DecimalType::I128,
472            DecimalType::I256
473        )]
474        target: DecimalType,
475    ) -> VortexResult<()> {
476        let values = [1i8, -2, 3];
477        let dtype = DecimalDType::new(2, 0);
478        let array = match_each_decimal_value_type!(storage, |S| {
479            let values = values.map(|value| {
480                <S as BigCast>::from(value).vortex_expect("small values fit every decimal type")
481            });
482            DecimalArray::new(Buffer::copy_from(values), dtype, Validity::NonNullable)
483        });
484
485        match_each_decimal_value_type!(target, |W| {
486            let converted = converted_buffer::<W>(&array, &Mask::new_true(values.len()))?;
487            let expected = values.map(|value| {
488                <W as BigCast>::from(value).vortex_expect("small values fit every decimal type")
489            });
490            assert_eq!(converted.as_slice(), expected.as_slice());
491        });
492        Ok(())
493    }
494
495    #[rstest]
496    #[case::i8_to_i16(DecimalType::I8, 3)]
497    #[case::i16_to_i32(DecimalType::I16, 5)]
498    #[case::i32_to_i64(DecimalType::I32, 10)]
499    #[case::i64_to_i128(DecimalType::I64, 19)]
500    #[case::i128_to_i256(DecimalType::I128, 39)]
501    #[case::i8_to_i256(DecimalType::I8, 76)]
502    #[case::i64_same_width(DecimalType::I64, 18)]
503    fn test_copy_to_canonical_width_widens(
504        #[case] source: DecimalType,
505        #[case] target_precision: u8,
506    ) -> VortexResult<()> {
507        let target = DecimalDType::new(target_precision, 2);
508        match_each_decimal_value_type!(source, |F| {
509            // The extremes of the largest precision that `F` holds, and zero.
510            let limit = ten_to_the(F::MAX_PRECISION) - i256::ONE;
511            let expected = [-limit, i256::ZERO, limit];
512            let values = to_native::<F>(&expected);
513            assert_eq!(copy_as_i256(&values, &Mask::new_true(3), target)?, expected);
514        });
515        Ok(())
516    }
517
518    /// Each case widens 130 values, so a vectorized loop runs its vector body and a scalar tail.
519    #[rstest]
520    #[case::i8_to_i16(DecimalType::I8, DecimalType::I16)]
521    #[case::i8_to_i32(DecimalType::I8, DecimalType::I32)]
522    #[case::i8_to_i64(DecimalType::I8, DecimalType::I64)]
523    #[case::i8_to_i128(DecimalType::I8, DecimalType::I128)]
524    #[case::i8_to_i256(DecimalType::I8, DecimalType::I256)]
525    #[case::i16_to_i32(DecimalType::I16, DecimalType::I32)]
526    #[case::i16_to_i64(DecimalType::I16, DecimalType::I64)]
527    #[case::i16_to_i128(DecimalType::I16, DecimalType::I128)]
528    #[case::i16_to_i256(DecimalType::I16, DecimalType::I256)]
529    #[case::i32_to_i64(DecimalType::I32, DecimalType::I64)]
530    #[case::i32_to_i128(DecimalType::I32, DecimalType::I128)]
531    #[case::i32_to_i256(DecimalType::I32, DecimalType::I256)]
532    #[case::i64_to_i128(DecimalType::I64, DecimalType::I128)]
533    #[case::i64_to_i256(DecimalType::I64, DecimalType::I256)]
534    #[case::i128_to_i256(DecimalType::I128, DecimalType::I256)]
535    fn test_widen_values_sign_extends(#[case] source: DecimalType, #[case] target: DecimalType) {
536        match_each_decimal_value_type!(source, |F| {
537            let small = |value: i8| {
538                <F as BigCast>::from(value).vortex_expect("small values fit every decimal type")
539            };
540            let pattern = [F::MIN, small(-1), small(0), small(1), F::MAX];
541            let values: Vec<F> = pattern.into_iter().cycle().take(130).collect();
542
543            match_each_decimal_value_type!(target, |W| {
544                let expected: Vec<W> = values
545                    .iter()
546                    .map(|&value| {
547                        <W as BigCast>::from(value)
548                            .vortex_expect("W is at least as wide as F, so every value fits")
549                    })
550                    .collect();
551                assert_eq!(
552                    widen_values::<F, W>(&values).as_slice(),
553                    expected.as_slice()
554                );
555            });
556        });
557    }
558
559    #[test]
560    #[should_panic(expected = "widen_values requires a target at least as wide as the source")]
561    fn test_widen_values_rejects_narrower_target() {
562        widen_values::<i64, i32>(&[1, 2, 3]);
563    }
564
565    /// Each case puts `10^p` inside the target width, so only the precision check can reject it.
566    #[rstest]
567    #[case::i16_to_i8(DecimalType::I16, 2)]
568    #[case::i32_to_i16(DecimalType::I32, 4)]
569    #[case::i64_to_i32(DecimalType::I64, 9)]
570    #[case::i128_to_i64(DecimalType::I128, 18)]
571    #[case::i256_to_i128(DecimalType::I256, 38)]
572    #[case::i256_to_i8(DecimalType::I256, 1)]
573    fn test_copy_to_canonical_width_narrowing_boundaries(
574        #[case] source: DecimalType,
575        #[case] target_precision: u8,
576    ) -> VortexResult<()> {
577        let target = DecimalDType::new(target_precision, 0);
578        let limit = ten_to_the(target_precision);
579        let inside = [-(limit - i256::ONE), limit - i256::ONE];
580        let outside = [-limit, limit];
581
582        match_each_decimal_value_type!(source, |F| {
583            let values = to_native::<F>(&inside);
584            assert_eq!(copy_as_i256(&values, &Mask::new_true(2), target)?, inside);
585
586            for value in to_native::<F>(&outside) {
587                assert!(copy_to_canonical_width(&[value], &Mask::new_true(1), target).is_err());
588            }
589        });
590        Ok(())
591    }
592
593    #[test]
594    fn test_copy_to_canonical_width_zeros_null_slots() -> VortexResult<()> {
595        // Row 1 holds a null value outside the `i32` width, and row 3 a null value inside the
596        // width but outside the precision.
597        let values = [12_345i128, 10i128.pow(30), -99_999, 100_000];
598        let validity = Mask::from_iter([true, false, true, false]);
599
600        let copy = copy_as_i256(&values, &validity, DecimalDType::new(5, 2))?;
601        assert_eq!(copy, [12_345, 0, -99_999, 0].map(i256::from_i128));
602        Ok(())
603    }
604
605    #[test]
606    fn test_copy_to_canonical_width_error_names_row() {
607        // Row 1 is a null slot outside the precision, so row 2 is the first failing valid row.
608        let values = [1i64, 1_000_000, 1_000, 5_000];
609        let validity = Mask::from_iter([true, false, true, true]);
610
611        let error = copy_to_canonical_width(&values, &validity, DecimalDType::new(3, 0))
612            .expect_err("row 2 is outside the precision")
613            .to_string();
614        assert!(error.contains("row 2"), "{error}");
615        assert!(error.contains("got 1000"), "{error}");
616        assert!(error.contains("decimal(3,0)"), "{error}");
617    }
618
619    #[test]
620    fn test_copy_to_canonical_width_all_null() -> VortexResult<()> {
621        let values = [10i128.pow(30), i128::MIN, 7];
622        let copy = copy_as_i256(&values, &Mask::new_false(3), DecimalDType::new(5, 2))?;
623        assert_eq!(copy, [i256::ZERO; 3]);
624        Ok(())
625    }
626
627    /// Precision 4 narrows the `i32` values, and precision 18 widens them.
628    #[rstest]
629    fn test_copy_to_canonical_width_length_mismatch(#[values(4, 18)] target_precision: u8) {
630        let target = DecimalDType::new(target_precision, 0);
631        let result = copy_to_canonical_width(&[1i32, 2, 3], &Mask::new_true(2), target);
632        assert!(result.is_err());
633    }
634
635    /// Each case puts `10^p` inside the width of the values, so only the precision rejects it.
636    #[rstest]
637    #[case::i8(DecimalType::I8, 2)]
638    #[case::i16(DecimalType::I16, 4)]
639    #[case::i32(DecimalType::I32, 9)]
640    #[case::i64(DecimalType::I64, 18)]
641    #[case::i128(DecimalType::I128, 38)]
642    #[case::i256(DecimalType::I256, 76)]
643    #[case::i128_below_max_precision(DecimalType::I128, 5)]
644    fn test_check_precision_boundaries(
645        #[case] values_type: DecimalType,
646        #[case] precision: u8,
647    ) -> VortexResult<()> {
648        let decimal_dtype = DecimalDType::new(precision, 0);
649        let limit = ten_to_the(precision);
650        let inside = [-(limit - i256::ONE), limit - i256::ONE];
651        let outside = [-limit, limit];
652
653        match_each_decimal_value_type!(values_type, |T| {
654            check_precision(&to_native::<T>(&inside), &Mask::new_true(2), decimal_dtype)?;
655
656            for value in to_native::<T>(&outside) {
657                assert!(check_precision(&[value], &Mask::new_true(1), decimal_dtype).is_err());
658            }
659        });
660        Ok(())
661    }
662
663    /// Every value of a type has at most one digit more than its `MAX_PRECISION`.
664    #[test]
665    fn test_check_precision_above_max_precision_of_values_type() -> VortexResult<()> {
666        let all_valid = Mask::new_true(2);
667        check_precision(&[i8::MIN, i8::MAX], &all_valid, DecimalDType::new(3, 0))?;
668        check_precision(&[i64::MIN, i64::MAX], &all_valid, DecimalDType::new(19, 0))?;
669        Ok(())
670    }
671
672    #[test]
673    fn test_check_precision_ignores_null_slots() -> VortexResult<()> {
674        let values = [5i32, 1_000_000_000, -7];
675        let validity = Mask::from_iter([true, false, true]);
676        let decimal_dtype = DecimalDType::new(4, 0);
677
678        check_precision(&values, &validity, decimal_dtype)?;
679        check_precision(&values, &Mask::new_false(3), decimal_dtype)?;
680        Ok(())
681    }
682}