Skip to main content

vortex_array/arrays/decimal/compute/
cast.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Decimal casts with checked precision, scale, and nullability.
5//!
6//! Same-scale casts that increase the canonical width defer the copy through a [`WidenArray`].
7//! Scale changes and precision reductions run the conversion kernel to check or rescale valid values.
8
9use num_traits::CheckedMul;
10use vortex_buffer::Buffer;
11use vortex_buffer::BufferMut;
12use vortex_compute::lane_kernels::IndexedSourceExt;
13use vortex_error::VortexError;
14use vortex_error::VortexExpect;
15use vortex_error::VortexResult;
16use vortex_error::vortex_bail;
17use vortex_error::vortex_err;
18use vortex_error::vortex_panic;
19use vortex_mask::Mask;
20
21use crate::ArrayRef;
22use crate::ExecutionCtx;
23use crate::IntoArray;
24use crate::array::ArrayView;
25use crate::arrays::ConstantArray;
26use crate::arrays::Decimal;
27use crate::arrays::DecimalArray;
28use crate::arrays::PrimitiveArray;
29use crate::arrays::WidenArray;
30use crate::arrays::decimal::DecimalArrayExt;
31use crate::dtype::BigCast;
32use crate::dtype::DType;
33use crate::dtype::DecimalDType;
34use crate::dtype::DecimalType;
35use crate::dtype::IntegerPType;
36use crate::dtype::NativeDecimalType;
37use crate::dtype::Nullability;
38use crate::dtype::PType;
39use crate::dtype::ToI256;
40use crate::dtype::i256;
41use crate::match_each_decimal_value_type;
42use crate::match_each_integer_ptype;
43use crate::scalar::DecimalToFloatCast;
44use crate::scalar::DecimalToIntegerCast;
45use crate::scalar::DecimalValue;
46use crate::scalar::Scalar;
47use crate::scalar_fn::fns::cast::CastKernel;
48use crate::scalar_fn::fns::cast::CastReduce;
49use crate::validity::Validity;
50
51impl CastReduce for Decimal {
52    fn cast(array: ArrayView<'_, Decimal>, dtype: &DType) -> VortexResult<Option<ArrayRef>> {
53        let DType::Decimal(to_decimal_dtype, to_nullability) = dtype else {
54            return Ok(None);
55        };
56        let DType::Decimal(from_decimal_dtype, _) = array.dtype() else {
57            vortex_panic!(
58                "DecimalArray must have decimal dtype, got {:?}",
59                array.dtype()
60            );
61        };
62
63        let grows_width = grows_canonical_width(*from_decimal_dtype, *to_decimal_dtype);
64        if from_decimal_dtype != to_decimal_dtype && !grows_width {
65            return Ok(None);
66        }
67
68        let Some(new_validity) = array
69            .validity()?
70            .trivially_cast_nullability(*to_nullability, array.len())?
71        else {
72            return Ok(None);
73        };
74
75        if grows_width {
76            return widen_decimal_values(array, dtype, new_validity).map(Some);
77        }
78
79        // SAFETY: validity has the same length, only its nullability tag changes.
80        unsafe {
81            Ok(Some(
82                DecimalArray::new_unchecked_handle(
83                    array.buffer_handle().clone(),
84                    array.values_type(),
85                    *to_decimal_dtype,
86                    new_validity,
87                )
88                .into_array(),
89            ))
90        }
91    }
92}
93
94impl CastKernel for Decimal {
95    fn cast(
96        array: ArrayView<'_, Decimal>,
97        dtype: &DType,
98        ctx: &mut ExecutionCtx,
99    ) -> VortexResult<Option<ArrayRef>> {
100        let DType::Decimal(from_decimal_dtype, _) = array.dtype() else {
101            vortex_panic!(
102                "DecimalArray must have decimal dtype, got {:?}",
103                array.dtype()
104            );
105        };
106        if let DType::Primitive(ptype, nullability) = dtype
107            && ptype.is_int()
108        {
109            return match_each_integer_ptype!(*ptype, |T| {
110                cast_to_integer::<T>(array, *nullability, ctx).map(Some)
111            });
112        }
113        if let DType::Primitive(PType::F64, nullability) = dtype {
114            let scale = from_decimal_dtype.scale();
115            return cast_to_f64(array, scale, *nullability, ctx).map(Some);
116        }
117        let DType::Decimal(to_decimal_dtype, to_nullability) = dtype else {
118            return Ok(None);
119        };
120
121        // If the dtype is exactly the same, return self
122        if array.dtype() == dtype {
123            return Ok(Some(array.array().clone()));
124        }
125
126        let validity = array.validity()?;
127
128        // Cast the validity to the new nullability
129        let new_validity = validity
130            .clone()
131            .cast_nullability(*to_nullability, array.len(), ctx)?;
132
133        if grows_canonical_width(*from_decimal_dtype, *to_decimal_dtype) {
134            return widen_decimal_values(array, dtype, new_validity).map(Some);
135        }
136
137        // Reuse the values buffer untouched when no rescale is required, the target precision
138        // only widens (so every value still fits), and the current physical type is already wide
139        // enough to hold the target precision. This keeps the common precision-widening cast
140        // (and pure nullability changes) zero-copy instead of allocating and re-scanning.
141        if from_decimal_dtype.scale() == to_decimal_dtype.scale()
142            && to_decimal_dtype.precision() >= from_decimal_dtype.precision()
143            && array
144                .values_type()
145                .is_compatible_decimal_value_type(*to_decimal_dtype)
146        {
147            // SAFETY: the source values are bit-identical and remain in range for the wider
148            // precision, and new_validity has the same length, only its nullability tag changes.
149            unsafe {
150                return Ok(Some(
151                    DecimalArray::new_unchecked_handle(
152                        array.buffer_handle().clone(),
153                        array.values_type(),
154                        *to_decimal_dtype,
155                        new_validity,
156                    )
157                    .into_array(),
158                ));
159            }
160        }
161
162        let valid_values = validity.execute_mask(array.len(), ctx)?;
163        if !array.is_empty() && matches!(valid_values, Mask::AllFalse(_)) {
164            return Ok(Some(
165                ConstantArray::new(Scalar::null(dtype.clone()), array.len()).into_array(),
166            ));
167        }
168        let target_values_type = to_decimal_dtype.canonical_values_type();
169
170        match_each_decimal_value_type!(array.values_type(), |F| {
171            match_each_decimal_value_type!(target_values_type, |T| {
172                cast_decimal_values::<F, T>(
173                    array,
174                    *from_decimal_dtype,
175                    *to_decimal_dtype,
176                    new_validity,
177                    &valid_values,
178                )
179                .map(Some)
180            })
181        })
182    }
183}
184
185/// Returns whether a same-scale cast increases the canonical width.
186fn grows_canonical_width(from: DecimalDType, to: DecimalDType) -> bool {
187    from.scale() == to.scale() && from.canonical_values_type() < to.canonical_values_type()
188}
189
190/// Wraps the source values in a [`WidenArray`] with the target dtype.
191///
192/// The caller must cast `validity` to the target nullability without changing its length or valid
193/// rows. The child keeps the source decimal dtype and statistics because its values are unchanged.
194fn widen_decimal_values(
195    array: ArrayView<'_, Decimal>,
196    dtype: &DType,
197    validity: Validity,
198) -> VortexResult<ArrayRef> {
199    let values = DecimalArray::new_handle(
200        array.buffer_handle().clone(),
201        array.values_type(),
202        array.decimal_dtype(),
203        validity,
204    );
205    values.statistics().inherit_from(array.statistics());
206
207    Ok(WidenArray::try_new(values.into_array(), dtype.clone())?.into_array())
208}
209
210fn cast_to_integer<T: IntegerPType + BigCast>(
211    array: ArrayView<'_, Decimal>,
212    nullability: Nullability,
213    ctx: &mut ExecutionCtx,
214) -> VortexResult<ArrayRef> {
215    let source_validity = array.validity()?;
216    let mask = source_validity.execute_mask(array.len(), ctx)?;
217    let validity = source_validity.cast_nullability(nullability, array.len(), ctx)?;
218    if !array.is_empty() && matches!(mask, Mask::AllFalse(_)) {
219        return Ok(ConstantArray::new(
220            Scalar::null(DType::Primitive(T::PTYPE, nullability)),
221            array.len(),
222        )
223        .into_array());
224    }
225    let cast = DecimalToIntegerCast::<T>::new(array.decimal_dtype().scale());
226    let buffer = match_each_decimal_value_type!(array.values_type(), |F| {
227        let values = array.buffer::<F>();
228        cast_decimal_buffer(values.as_slice(), &mask, |value: F| {
229            cast.cast(value.to_i256()?)
230        })
231        .map_err(|index| cast.error(DecimalValue::from(values[index]).as_i256()))?
232    });
233    Ok(PrimitiveArray::new(buffer, validity).into_array())
234}
235
236fn cast_to_f64(
237    array: ArrayView<'_, Decimal>,
238    scale: i8,
239    nullability: Nullability,
240    ctx: &mut ExecutionCtx,
241) -> VortexResult<ArrayRef> {
242    let source_validity = array.validity()?;
243    let n = array.len();
244    let mask = source_validity.execute_mask(n, ctx)?;
245    let validity = source_validity.cast_nullability(nullability, n, ctx)?;
246    if n > 0 && matches!(mask, Mask::AllFalse(_)) {
247        return Ok(
248            ConstantArray::new(Scalar::null(DType::Primitive(PType::F64, nullability)), n)
249                .into_array(),
250        );
251    }
252
253    let cast = DecimalToFloatCast::new(scale);
254
255    let buffer = match &mask {
256        Mask::AllFalse(_) => BufferMut::<f64>::zeroed(n),
257        Mask::AllTrue(_) => match_each_decimal_value_type!(array.values_type(), |F| {
258            let values = array.buffer::<F>();
259            let values = values.as_slice();
260            let mut out = BufferMut::<f64>::with_capacity(n);
261            values.map_into(&mut out.spare_capacity_mut()[..n], |v: F| cast.cast(v));
262            // SAFETY: map_into wrote every lane before returning.
263            unsafe { out.set_len(n) };
264            out
265        }),
266        Mask::Values(mask_values) => match_each_decimal_value_type!(array.values_type(), |F| {
267            let values = array.buffer::<F>();
268            let values = values.as_slice();
269            let mut out = BufferMut::<f64>::with_capacity(n);
270            let write_result = values.try_map_masked_into(
271                mask_values.bit_buffer(),
272                &mut out.spare_capacity_mut()[..n],
273                |v: F| Some(cast.cast(v)),
274            );
275            debug_assert!(write_result.is_ok());
276            // SAFETY: try_map_masked_into wrote every lane before returning Ok.
277            unsafe { out.set_len(n) };
278            out
279        }),
280    };
281
282    Ok(PrimitiveArray::new(buffer, validity).into_array())
283}
284
285fn cast_decimal_values<F, T>(
286    array: ArrayView<'_, Decimal>,
287    from_decimal_dtype: DecimalDType,
288    to_decimal_dtype: DecimalDType,
289    validity: Validity,
290    valid_values: &Mask,
291) -> VortexResult<ArrayRef>
292where
293    F: NativeDecimalType,
294    T: NativeDecimalType + CheckedMul,
295    DecimalValue: From<F>,
296{
297    let values = array.buffer::<F>();
298    let values = values.as_slice();
299    let cast_result = match DecimalCastPlan::<T>::new(from_decimal_dtype, to_decimal_dtype) {
300        DecimalCastPlan::SameScale { min, max } => {
301            cast_decimal_buffer(values, valid_values, |value| {
302                let value = <T as BigCast>::from(value)?;
303                (value >= min && value <= max).then_some(value)
304            })
305        }
306        cast_plan => cast_decimal_buffer(values, valid_values, |value| cast_plan.cast(value)),
307    };
308    let buffer = cast_result.map_err(|idx| {
309        decimal_cast_error::<F, T>(values[idx], from_decimal_dtype, to_decimal_dtype)
310    })?;
311
312    Ok(DecimalArray::new(buffer, to_decimal_dtype, validity).into_array())
313}
314
315fn cast_decimal_buffer<F, T>(
316    values: &[F],
317    valid_values: &Mask,
318    cast: impl Fn(F) -> Option<T>,
319) -> Result<Buffer<T>, usize>
320where
321    F: NativeDecimalType,
322    T: Copy + Default,
323{
324    let mut buffer = BufferMut::<T>::with_capacity(values.len());
325    match valid_values {
326        Mask::AllTrue(_) => {
327            values.try_map_into(&mut buffer.spare_capacity_mut()[..values.len()], &cast)?;
328        }
329        Mask::AllFalse(_) => return Ok(BufferMut::<T>::zeroed(values.len()).freeze()),
330        Mask::Values(mask) => {
331            values.try_map_masked_into(
332                mask.bit_buffer(),
333                &mut buffer.spare_capacity_mut()[..values.len()],
334                &cast,
335            )?;
336        }
337    }
338    // SAFETY: the selected map kernel initialized every lane before returning Ok.
339    unsafe { buffer.set_len(values.len()) };
340    Ok(buffer.freeze())
341}
342
343#[cold]
344fn decimal_cast_error<F, T>(
345    value: F,
346    from_decimal_dtype: DecimalDType,
347    to_decimal_dtype: DecimalDType,
348) -> VortexError
349where
350    F: NativeDecimalType,
351    T: NativeDecimalType,
352    DecimalValue: From<F>,
353{
354    match DecimalValue::from(value)
355        .cast_decimal(from_decimal_dtype, to_decimal_dtype)
356        .and_then(|value| {
357            value.cast::<T>().ok_or_else(|| {
358                vortex_err!(
359                    "decimal value cannot be represented as {} after casting to {}",
360                    T::DECIMAL_TYPE,
361                    to_decimal_dtype
362                )
363            })
364        }) {
365        Ok(_) => {
366            // The fast path only returns `None` for values the slow path also rejects, so this
367            // arm should be unreachable. If it is hit, the fast and slow paths have drifted and
368            // we are erroring on a value that is actually representable.
369            debug_assert!(
370                false,
371                "decimal fast-path cast rejected value {value} that the slow path accepts \
372                 (from {from_decimal_dtype} to {to_decimal_dtype})"
373            );
374            vortex_err!(
375                "decimal value cannot be represented as {} after casting from {} to {}",
376                T::DECIMAL_TYPE,
377                from_decimal_dtype,
378                to_decimal_dtype
379            )
380        }
381        Err(error) => error,
382    }
383}
384
385#[derive(Debug, Clone, Copy)]
386enum DecimalCastPlan<T> {
387    SameScale { min: T, max: T },
388    ScaleUp { factor: T, min: T, max: T },
389    ScaleUpOverflow,
390    ScaleDown { factor: i256, min: i256, max: i256 },
391    ScaleDownOverflow,
392}
393
394impl<T> DecimalCastPlan<T>
395where
396    T: NativeDecimalType + CheckedMul,
397{
398    fn new(from_decimal_dtype: DecimalDType, to_decimal_dtype: DecimalDType) -> Self {
399        let scale_delta = to_decimal_dtype.scale() as i16 - from_decimal_dtype.scale() as i16;
400        if scale_delta == 0 {
401            let (min, max) = decimal_precision_range::<T>(to_decimal_dtype);
402            return Self::SameScale { min, max };
403        }
404
405        if scale_delta > 0 {
406            let Some(factor) = decimal_scale_factor::<T>(scale_delta as u32) else {
407                return Self::ScaleUpOverflow;
408            };
409            let (min, max) = decimal_precision_range::<T>(to_decimal_dtype);
410            return Self::ScaleUp { factor, min, max };
411        }
412
413        let Some(factor) = decimal_scale_factor::<i256>((-scale_delta) as u32) else {
414            return Self::ScaleDownOverflow;
415        };
416        let (min, max) = decimal_precision_range::<i256>(to_decimal_dtype);
417        Self::ScaleDown { factor, min, max }
418    }
419
420    #[inline]
421    fn cast<F>(&self, value: F) -> Option<T>
422    where
423        F: NativeDecimalType,
424    {
425        match *self {
426            DecimalCastPlan::SameScale { min, max } => {
427                let value = <T as BigCast>::from(value)?;
428                (value >= min && value <= max).then_some(value)
429            }
430            DecimalCastPlan::ScaleUp { factor, min, max } => {
431                let value = <T as BigCast>::from(value)?;
432                let value = value.checked_mul(&factor)?;
433                (value >= min && value <= max).then_some(value)
434            }
435            DecimalCastPlan::ScaleUpOverflow | DecimalCastPlan::ScaleDownOverflow => {
436                (value == F::default()).then_some(T::default())
437            }
438            DecimalCastPlan::ScaleDown { factor, min, max } => {
439                let value = <i256 as BigCast>::from(value)?;
440                if value == i256::ZERO {
441                    return Some(T::default());
442                }
443                if value % factor != i256::ZERO {
444                    return None;
445                }
446
447                let value = value / factor;
448                if value < min || value > max {
449                    return None;
450                }
451                <T as BigCast>::from(value)
452            }
453        }
454    }
455}
456
457fn decimal_precision_range<T: NativeDecimalType>(decimal_dtype: DecimalDType) -> (T, T) {
458    let precision = usize::from(decimal_dtype.precision());
459    (
460        T::MIN_BY_PRECISION[precision],
461        T::MAX_BY_PRECISION[precision],
462    )
463}
464
465fn decimal_scale_factor<T>(exp: u32) -> Option<T>
466where
467    T: NativeDecimalType + CheckedMul,
468{
469    let ten = <T as BigCast>::from(10_i8)?;
470    let mut factor = <T as BigCast>::from(1_i8)?;
471    for _ in 0..exp {
472        factor = factor.checked_mul(&ten)?;
473    }
474    Some(factor)
475}
476
477/// Upcast a DecimalArray to a wider physical representation (e.g., i32 -> i64) while keeping
478/// the same precision and scale.
479///
480/// This is useful when you need to widen the underlying storage type to accommodate operations
481/// that might overflow the current representation, or to match the physical type expected by
482/// downstream consumers.
483///
484/// # Errors
485///
486/// Returns an error if `to_values_type` is narrower than the array's current values type.
487/// Only upcasting (widening) is supported.
488pub fn upcast_decimal_values(
489    array: ArrayView<'_, Decimal>,
490    to_values_type: DecimalType,
491) -> VortexResult<DecimalArray> {
492    let from_values_type = array.values_type();
493
494    // If already the target type, just clone
495    if from_values_type == to_values_type {
496        return Ok(array.array().as_::<Decimal>().into_owned());
497    }
498
499    // Only allow upcasting (widening)
500    if to_values_type < from_values_type {
501        vortex_bail!(
502            "Cannot downcast decimal values from {:?} to {:?}. Only upcasting is supported.",
503            from_values_type,
504            to_values_type
505        );
506    }
507
508    let decimal_dtype = array.decimal_dtype();
509    let validity = array.validity()?;
510
511    // Use match_each_decimal_value_type to dispatch based on source and target types
512    match_each_decimal_value_type!(from_values_type, |F| {
513        let from_buffer = array.buffer::<F>();
514        match_each_decimal_value_type!(to_values_type, |T| {
515            let to_buffer = upcast_decimal_buffer::<F, T>(from_buffer);
516            Ok(DecimalArray::new(to_buffer, decimal_dtype, validity))
517        })
518    })
519}
520
521/// Upcast a buffer of decimal values from type F to type T.
522/// Since T is wider than F, this conversion never fails.
523fn upcast_decimal_buffer<F: NativeDecimalType, T: NativeDecimalType>(from: Buffer<F>) -> Buffer<T> {
524    from.iter()
525        .map(|&v| T::from(v).vortex_expect("upcast should never fail"))
526        .collect()
527}
528
529#[cfg(test)]
530mod tests {
531    use std::sync::LazyLock;
532
533    use rstest::rstest;
534    use vortex_buffer::buffer;
535    use vortex_error::VortexResult;
536    use vortex_session::VortexSession;
537
538    use super::upcast_decimal_values;
539    use crate::Canonical;
540    use crate::IntoArray;
541    use crate::VortexSessionExecute;
542    use crate::arrays::DecimalArray;
543    use crate::arrays::PrimitiveArray;
544    use crate::assert_arrays_eq;
545    use crate::builtins::ArrayBuiltins;
546    use crate::compute::conformance::cast::test_cast_conformance;
547    use crate::dtype::BigCast;
548    use crate::dtype::DType;
549    use crate::dtype::DecimalDType;
550    use crate::dtype::DecimalType;
551    use crate::dtype::Nullability;
552    use crate::dtype::PType;
553    use crate::dtype::i256;
554    use crate::match_each_decimal_value_type;
555    use crate::match_each_integer_ptype;
556    use crate::scalar::Scalar;
557    use crate::validity::Validity;
558
559    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
560
561    #[rstest]
562    #[case::workflow(0, vec![0, 1], vec![0, 1])]
563    #[case::fractional(1, vec![-199, -1, 0, 1, 199], vec![-19, 0, 0, 0, 19])]
564    #[case::negative_scale(-2, vec![-12, 0, 12], vec![-1200, 0, 1200])]
565    #[case::large_exact(
566        0,
567        vec![1_786_639_777_684_000_001],
568        vec![1_786_639_777_684_000_001]
569    )]
570    #[case::large_scale(76, vec![-1, 1], vec![0, 0])]
571    #[case::zero_extreme_scale(-128, vec![0, 0], vec![0, 0])]
572    fn cast_decimal_to_integer_policy(
573        #[case] scale: i8,
574        #[case] values: Vec<i128>,
575        #[case] expected: Vec<i64>,
576    ) -> VortexResult<()> {
577        let mut ctx = SESSION.create_execution_ctx();
578        let decimal_dtype = DecimalDType::new(76, scale);
579        let array = DecimalArray::new(
580            values.iter().copied().map(i256::from_i128).collect(),
581            decimal_dtype,
582            Validity::NonNullable,
583        );
584        let target = DType::Primitive(PType::I64, Nullability::NonNullable);
585        let casted = array.into_array().cast(target.clone())?;
586        assert_arrays_eq!(
587            casted,
588            PrimitiveArray::from_iter(expected.iter().copied()),
589            &mut ctx
590        );
591        for (value, expected) in values.into_iter().zip(expected) {
592            let scalar = Scalar::decimal(value.into(), decimal_dtype, Nullability::NonNullable);
593            assert_eq!(scalar.cast(&target)?, Scalar::from(expected));
594        }
595        Ok(())
596    }
597
598    #[rstest]
599    #[case::exact_scale(2)]
600    #[case::inexact_scale(30)]
601    #[case::past_i128_scale(39)]
602    #[case::max_scale(76)]
603    #[case::negative_scale(-5)]
604    #[case::extreme_negative_scale(-128)]
605    fn cast_decimal_to_f64_matches_scalar_cast(#[case] scale: i8) -> VortexResult<()> {
606        let mut ctx = SESSION.create_execution_ctx();
607        let decimal_dtype = DecimalDType::new(76, scale);
608        let beyond_i128 = i256::from_i128(i128::MAX) + i256::ONE;
609        let values = vec![
610            i256::ZERO,
611            i256::from_i128(12345),
612            i256::from_i128(-7),
613            i256::from_i128(i64::MAX.into()) + i256::ONE,
614            beyond_i128,
615            -beyond_i128,
616        ];
617        let array = DecimalArray::new(
618            values.iter().copied().collect(),
619            decimal_dtype,
620            Validity::NonNullable,
621        );
622
623        let target = DType::Primitive(PType::F64, Nullability::NonNullable);
624        let casted = array
625            .into_array()
626            .cast(target.clone())?
627            .execute::<PrimitiveArray>(&mut ctx)?;
628
629        assert_eq!(casted.len(), values.len());
630        assert_eq!(casted.dtype(), &target);
631        for (value, array_value) in values.into_iter().zip(casted.as_slice::<f64>()) {
632            let scalar = Scalar::decimal(value.into(), decimal_dtype, Nullability::NonNullable);
633            let scalar_value = f64::try_from(&scalar.cast(&target)?)?;
634            assert!(
635                !array_value.is_nan(),
636                "{value} at scale {scale} cast to NaN"
637            );
638            assert_eq!(
639                array_value.to_bits(),
640                scalar_value.to_bits(),
641                "{value} at scale {scale}: array {array_value}, scalar {scalar_value}"
642            );
643        }
644
645        Ok(())
646    }
647
648    #[rstest]
649    fn cast_decimal_to_integer_storage_and_nulls(
650        #[values(
651            DecimalType::I8,
652            DecimalType::I16,
653            DecimalType::I32,
654            DecimalType::I64,
655            DecimalType::I128,
656            DecimalType::I256
657        )]
658        storage: DecimalType,
659        #[values(
660            PType::I8, PType::I16, PType::I32, PType::I64, PType::U8, PType::U16, PType::U32,
661            PType::U64
662        )]
663        target: PType,
664    ) -> VortexResult<()> {
665        let mut ctx = SESSION.create_execution_ctx();
666        let decimal_dtype = DecimalDType::new(3, 1);
667        let array = match_each_decimal_value_type!(storage, |F| {
668            DecimalArray::from_option_iter(
669                [Some(19i8), None, Some(123)].map(|value| value.and_then(<F as BigCast>::from)),
670                decimal_dtype,
671            )
672        });
673        let dtype = DType::Primitive(target, Nullability::Nullable);
674        let casted = array.into_array().cast(dtype.clone())?;
675        match_each_integer_ptype!(target, |T| {
676            assert_arrays_eq!(
677                casted,
678                PrimitiveArray::from_option_iter([Some(1 as T), None, Some(12 as T)]),
679                &mut ctx
680            );
681            for (value, expected) in [(19i8, 1 as T), (123, 12 as T)] {
682                let scalar = Scalar::decimal(value.into(), decimal_dtype, Nullability::Nullable);
683                assert_eq!(
684                    scalar.cast(&dtype)?,
685                    Scalar::primitive(expected, Nullability::Nullable)
686                );
687            }
688        });
689        Ok(())
690    }
691
692    #[rstest]
693    fn cast_decimal_to_integer_bounds(
694        #[values(
695            PType::I8, PType::I16, PType::I32, PType::I64, PType::U8, PType::U16, PType::U32,
696            PType::U64
697        )]
698        target: PType,
699    ) -> VortexResult<()> {
700        let mut ctx = SESSION.create_execution_ctx();
701        let decimal_dtype = DecimalDType::new(76, 1);
702        let dtype = DType::Primitive(target, Nullability::NonNullable);
703        match_each_integer_ptype!(target, |T| {
704            let ten = i256::from_i128(10);
705            let minimum = i256::from_i128(T::MIN as i128) * ten;
706            let maximum = i256::from_i128(T::MAX as i128) * ten;
707            let array = DecimalArray::new(
708                buffer![minimum, maximum],
709                decimal_dtype,
710                Validity::NonNullable,
711            );
712            let casted = array.into_array().cast(dtype.clone())?;
713            assert_arrays_eq!(
714                casted,
715                PrimitiveArray::from_iter([T::MIN, T::MAX]),
716                &mut ctx
717            );
718            for (value, expected) in [(minimum, T::MIN), (maximum, T::MAX)] {
719                let scalar = Scalar::decimal(value.into(), decimal_dtype, Nullability::NonNullable);
720                assert_eq!(
721                    scalar.cast(&dtype)?,
722                    Scalar::primitive(expected, Nullability::NonNullable)
723                );
724            }
725            // The scalar policy rejects values outside the range even when truncation would fit.
726            for value in [
727                minimum - i256::ONE,
728                maximum + i256::ONE,
729                minimum - ten,
730                maximum + ten,
731            ] {
732                let array = DecimalArray::new(
733                    buffer![i256::ZERO, value],
734                    decimal_dtype,
735                    Validity::NonNullable,
736                );
737                let error = array
738                    .into_array()
739                    .cast(dtype.clone())?
740                    .execute::<PrimitiveArray>(&mut ctx)
741                    .unwrap_err();
742                assert!(error.to_string().contains("out of range"));
743                let scalar = Scalar::decimal(value.into(), decimal_dtype, Nullability::NonNullable);
744                assert!(scalar.cast(&dtype).is_err());
745            }
746        });
747        Ok(())
748    }
749
750    #[test]
751    fn cast_decimal_to_integer_masks_and_empty() -> VortexResult<()> {
752        let mut ctx = SESSION.create_execution_ctx();
753        let decimal_dtype = DecimalDType::new(21, 0);
754        let target = DType::Primitive(PType::I8, Nullability::Nullable);
755        for validity in [Validity::from_iter([false, true]), Validity::AllInvalid] {
756            let expected = PrimitiveArray::new(buffer![0i8, 12], validity.clone());
757            let array = DecimalArray::new(buffer![999i128, 12], decimal_dtype, validity);
758            let casted = array.into_array().cast(target.clone())?;
759            assert_arrays_eq!(casted, expected, &mut ctx);
760        }
761        let array = DecimalArray::new(
762            buffer![999i128, 12],
763            decimal_dtype,
764            Validity::from_iter([false, true]),
765        );
766        assert!(
767            array
768                .into_array()
769                .cast(target.as_nonnullable())?
770                .execute::<PrimitiveArray>(&mut ctx)
771                .is_err()
772        );
773        let empty = DecimalArray::from_option_iter([] as [Option<i128>; 0], decimal_dtype);
774        let casted = empty.into_array().cast(target.as_nonnullable())?;
775        assert_arrays_eq!(casted, PrimitiveArray::from_iter([] as [i8; 0]), &mut ctx);
776        Ok(())
777    }
778
779    #[test]
780    fn cast_decimal_to_integer_wide_storage() -> VortexResult<()> {
781        let mut ctx = SESSION.create_execution_ctx();
782        let factor = i256::from_i128(10).checked_pow(40).unwrap();
783        let value = i256::from_i128(123) * factor + i256::ONE;
784        let decimal_dtype = DecimalDType::new(76, 40);
785        let target = DType::Primitive(PType::I64, Nullability::NonNullable);
786        let array = DecimalArray::new(buffer![value, -value], decimal_dtype, Validity::NonNullable);
787        let casted = array.into_array().cast(target.clone())?;
788        assert_arrays_eq!(casted, PrimitiveArray::from_iter([123i64, -123]), &mut ctx);
789        for (value, expected) in [(value, 123i64), (-value, -123)] {
790            let scalar = Scalar::decimal(value.into(), decimal_dtype, Nullability::NonNullable);
791            assert_eq!(scalar.cast(&target)?, Scalar::from(expected));
792        }
793        let huge = DecimalArray::new(
794            buffer![i256::ONE],
795            DecimalDType::new(1, -128),
796            Validity::NonNullable,
797        );
798        assert!(
799            huge.into_array()
800                .cast(target)?
801                .execute::<PrimitiveArray>(&mut ctx)
802                .is_err()
803        );
804        Ok(())
805    }
806
807    #[test]
808    fn cast_decimal_to_nullable() {
809        let mut ctx = SESSION.create_execution_ctx();
810        let decimal_dtype = DecimalDType::new(10, 2);
811        let array = DecimalArray::new(
812            buffer![100i32, 200, 300],
813            decimal_dtype,
814            Validity::NonNullable,
815        );
816
817        // Cast to nullable
818        let nullable_dtype = DType::Decimal(decimal_dtype, Nullability::Nullable);
819        let casted = array
820            .into_array()
821            .cast(nullable_dtype.clone())
822            .unwrap()
823            .execute::<DecimalArray>(&mut ctx)
824            .unwrap();
825
826        assert_eq!(casted.dtype(), &nullable_dtype);
827        assert!(matches!(casted.validity(), Ok(Validity::AllValid)));
828        assert_eq!(casted.len(), 3);
829        assert_arrays_eq!(
830            casted,
831            DecimalArray::new(buffer![100i32, 200, 300], decimal_dtype, Validity::AllValid),
832            &mut ctx
833        );
834    }
835
836    #[test]
837    fn cast_nullable_to_non_nullable() {
838        let mut ctx = SESSION.create_execution_ctx();
839        let decimal_dtype = DecimalDType::new(10, 2);
840
841        // Create nullable array with no nulls
842        let array = DecimalArray::new(buffer![100i32, 200, 300], decimal_dtype, Validity::AllValid);
843
844        // Cast to non-nullable
845        let non_nullable_dtype = DType::Decimal(decimal_dtype, Nullability::NonNullable);
846        let casted = array
847            .into_array()
848            .cast(non_nullable_dtype.clone())
849            .unwrap()
850            .execute::<DecimalArray>(&mut ctx)
851            .unwrap();
852
853        assert_eq!(casted.dtype(), &non_nullable_dtype);
854        assert!(matches!(casted.validity(), Ok(Validity::NonNullable)));
855        assert_arrays_eq!(
856            casted,
857            DecimalArray::new(
858                buffer![100i32, 200, 300],
859                decimal_dtype,
860                Validity::NonNullable
861            ),
862            &mut ctx
863        );
864    }
865
866    #[test]
867    #[should_panic(expected = "Cannot cast array with invalid values to non-nullable type")]
868    fn cast_nullable_with_nulls_to_non_nullable_fails() {
869        let mut ctx = SESSION.create_execution_ctx();
870        let decimal_dtype = DecimalDType::new(10, 2);
871
872        // Create nullable array with nulls
873        let array = DecimalArray::from_option_iter([Some(100i32), None, Some(300)], decimal_dtype);
874
875        // Attempt to cast to non-nullable should fail
876        let non_nullable_dtype = DType::Decimal(decimal_dtype, Nullability::NonNullable);
877        array
878            .into_array()
879            .cast(non_nullable_dtype)
880            .and_then(|a| a.execute::<Canonical>(&mut ctx).map(|c| c.into_array()))
881            .unwrap();
882    }
883
884    #[test]
885    fn cast_different_scale_rescales() {
886        let mut ctx = SESSION.create_execution_ctx();
887        let array = DecimalArray::new(
888            buffer![100i32],
889            DecimalDType::new(10, 2),
890            Validity::NonNullable,
891        );
892
893        // Cast 1.00 to scale 3, where it is stored as 1000.
894        let different_dtype = DType::Decimal(DecimalDType::new(15, 3), Nullability::NonNullable);
895        let casted = array
896            .into_array()
897            .cast(different_dtype)
898            .unwrap()
899            .execute::<DecimalArray>(&mut ctx)
900            .unwrap();
901
902        assert_eq!(casted.precision(), 15);
903        assert_eq!(casted.scale(), 3);
904        assert_eq!(casted.values_type(), DecimalType::I64);
905        assert_eq!(casted.buffer::<i64>().as_ref(), &[1000]);
906    }
907
908    #[test]
909    fn cast_downcast_precision_succeeds_when_values_fit() {
910        let mut ctx = SESSION.create_execution_ctx();
911        let array = DecimalArray::new(
912            buffer![100i64],
913            DecimalDType::new(18, 2),
914            Validity::NonNullable,
915        );
916
917        // Downcasting precision is allowed when every value fits.
918        let smaller_dtype = DType::Decimal(DecimalDType::new(10, 2), Nullability::NonNullable);
919        let casted = array
920            .into_array()
921            .cast(smaller_dtype)
922            .unwrap()
923            .execute::<DecimalArray>(&mut ctx)
924            .unwrap();
925
926        assert_eq!(casted.precision(), 10);
927        assert_eq!(casted.scale(), 2);
928        assert_eq!(casted.buffer::<i64>().as_ref(), &[100]);
929    }
930
931    #[test]
932    fn cast_downcast_precision_checks_values() {
933        let mut ctx = SESSION.create_execution_ctx();
934        let array = DecimalArray::new(
935            buffer![1000i64],
936            DecimalDType::new(18, 0),
937            Validity::NonNullable,
938        );
939
940        let smaller_dtype = DType::Decimal(DecimalDType::new(3, 0), Nullability::NonNullable);
941        let result = array
942            .into_array()
943            .cast(smaller_dtype)
944            .and_then(|a| a.execute::<Canonical>(&mut ctx).map(|c| c.into_array()));
945
946        assert!(result.is_err());
947        assert!(
948            result
949                .unwrap_err()
950                .to_string()
951                .contains("does not fit in precision")
952        );
953    }
954
955    #[test]
956    fn cast_lower_scale_requires_exact_rescale() {
957        let mut ctx = SESSION.create_execution_ctx();
958        let array = DecimalArray::new(
959            buffer![123456i64],
960            DecimalDType::new(10, 4),
961            Validity::NonNullable,
962        );
963
964        let lower_scale_dtype = DType::Decimal(DecimalDType::new(10, 2), Nullability::NonNullable);
965        let result = array
966            .into_array()
967            .cast(lower_scale_dtype)
968            .and_then(|a| a.execute::<Canonical>(&mut ctx).map(|c| c.into_array()));
969
970        assert!(result.is_err());
971        assert!(
972            result
973                .unwrap_err()
974                .to_string()
975                .contains("would lose precision")
976        );
977    }
978
979    #[test]
980    fn cast_lower_scale_ignores_null_lane_failures() {
981        let mut ctx = SESSION.create_execution_ctx();
982        let array = DecimalArray::new(
983            buffer![100i64, 123456],
984            DecimalDType::new(10, 4),
985            Validity::from_iter([true, false]),
986        );
987
988        let lower_scale_dtype = DType::Decimal(DecimalDType::new(3, 2), Nullability::Nullable);
989        let casted = array
990            .into_array()
991            .cast(lower_scale_dtype)
992            .unwrap()
993            .execute::<DecimalArray>(&mut ctx)
994            .unwrap();
995
996        let mask = casted
997            .as_ref()
998            .validity()
999            .unwrap()
1000            .execute_mask(casted.as_ref().len(), &mut SESSION.create_execution_ctx())
1001            .unwrap();
1002        assert!(mask.value(0));
1003        assert!(!mask.value(1));
1004        assert_eq!(casted.buffer::<i16>().as_ref()[0], 1);
1005    }
1006
1007    #[test]
1008    fn cast_to_non_decimal_returns_err() {
1009        let mut ctx = SESSION.create_execution_ctx();
1010        let array = DecimalArray::new(
1011            buffer![100i32],
1012            DecimalDType::new(10, 2),
1013            Validity::NonNullable,
1014        );
1015
1016        // Try to cast to non-decimal type - should fail since no kernel can handle it
1017        let result = array
1018            .into_array()
1019            .cast(DType::Utf8(Nullability::NonNullable))
1020            .and_then(|a| a.execute::<Canonical>(&mut ctx).map(|c| c.into_array()));
1021
1022        assert!(result.is_err());
1023        assert!(
1024            result
1025                .unwrap_err()
1026                .to_string()
1027                .contains("No CastKernel to cast canonical array")
1028        );
1029    }
1030
1031    #[rstest]
1032    #[case(DecimalArray::new(buffer![100i32, 200, 300], DecimalDType::new(10, 2), Validity::NonNullable))]
1033    #[case(DecimalArray::new(buffer![10000i64, 20000, 30000], DecimalDType::new(18, 4), Validity::NonNullable))]
1034    #[case(DecimalArray::from_option_iter([Some(100i32), None, Some(300)], DecimalDType::new(10, 2)))]
1035    #[case(DecimalArray::new(buffer![42i32], DecimalDType::new(5, 1), Validity::NonNullable))]
1036    fn test_cast_decimal_conformance(#[case] array: DecimalArray) {
1037        test_cast_conformance(&array.into_array(), &mut SESSION.create_execution_ctx());
1038    }
1039
1040    #[test]
1041    fn upcast_decimal_values_i32_to_i64() {
1042        let decimal_dtype = DecimalDType::new(10, 2);
1043        let array = DecimalArray::new(
1044            buffer![100i32, 200, 300],
1045            decimal_dtype,
1046            Validity::NonNullable,
1047        );
1048
1049        assert_eq!(array.values_type(), DecimalType::I32);
1050
1051        let array = array.as_view();
1052        let casted = upcast_decimal_values(array, DecimalType::I64).unwrap();
1053
1054        assert_eq!(casted.values_type(), DecimalType::I64);
1055        assert_eq!(casted.decimal_dtype(), decimal_dtype);
1056        assert_eq!(casted.len(), 3);
1057
1058        // Verify values are preserved
1059        let buffer = casted.buffer::<i64>();
1060        assert_eq!(buffer.as_ref(), &[100i64, 200, 300]);
1061    }
1062
1063    #[test]
1064    fn upcast_decimal_values_i64_to_i128() {
1065        let decimal_dtype = DecimalDType::new(18, 4);
1066        let array = DecimalArray::new(
1067            buffer![10000i64, 20000, 30000],
1068            decimal_dtype,
1069            Validity::NonNullable,
1070        );
1071
1072        let array = array.as_view();
1073        let casted = upcast_decimal_values(array, DecimalType::I128).unwrap();
1074
1075        assert_eq!(casted.values_type(), DecimalType::I128);
1076        assert_eq!(casted.decimal_dtype(), decimal_dtype);
1077
1078        let buffer = casted.buffer::<i128>();
1079        assert_eq!(buffer.as_ref(), &[10000i128, 20000, 30000]);
1080    }
1081
1082    #[test]
1083    fn upcast_decimal_values_same_type_returns_clone() {
1084        let decimal_dtype = DecimalDType::new(10, 2);
1085        let array = DecimalArray::new(
1086            buffer![100i32, 200, 300],
1087            decimal_dtype,
1088            Validity::NonNullable,
1089        );
1090
1091        let array = array.as_view();
1092        let casted = upcast_decimal_values(array, DecimalType::I32).unwrap();
1093
1094        assert_eq!(casted.values_type(), DecimalType::I32);
1095        assert_eq!(casted.decimal_dtype(), decimal_dtype);
1096        assert_arrays_eq!(
1097            casted,
1098            DecimalArray::from_iter([100i32, 200, 300], decimal_dtype),
1099            &mut SESSION.create_execution_ctx()
1100        );
1101    }
1102
1103    #[test]
1104    fn upcast_decimal_values_with_nulls() {
1105        let decimal_dtype = DecimalDType::new(10, 2);
1106        let array = DecimalArray::from_option_iter([Some(100i32), None, Some(300)], decimal_dtype);
1107
1108        let array = array.as_view();
1109        let casted = upcast_decimal_values(array, DecimalType::I64).unwrap();
1110
1111        assert_eq!(casted.values_type(), DecimalType::I64);
1112        assert_eq!(casted.len(), 3);
1113
1114        // Check validity is preserved
1115        let mask = casted
1116            .as_ref()
1117            .validity()
1118            .unwrap()
1119            .execute_mask(casted.as_ref().len(), &mut SESSION.create_execution_ctx())
1120            .unwrap();
1121        assert!(mask.value(0));
1122        assert!(!mask.value(1));
1123        assert!(mask.value(2));
1124
1125        // Check non-null values
1126        let buffer = casted.buffer::<i64>();
1127        assert_eq!(buffer[0], 100);
1128        assert_eq!(buffer[2], 300);
1129    }
1130
1131    #[test]
1132    fn upcast_decimal_values_downcast_fails() {
1133        let decimal_dtype = DecimalDType::new(18, 4);
1134        let array = DecimalArray::new(
1135            buffer![10000i64, 20000, 30000],
1136            decimal_dtype,
1137            Validity::NonNullable,
1138        );
1139
1140        // Attempt to downcast from i64 to i32 should fail
1141        let array = array.as_view();
1142        let result = upcast_decimal_values(array, DecimalType::I32);
1143        assert!(result.is_err());
1144        assert!(
1145            result
1146                .unwrap_err()
1147                .to_string()
1148                .contains("Cannot downcast decimal values")
1149        );
1150    }
1151
1152    #[test]
1153    fn cast_decimal_f64() {
1154        let dtype = DecimalDType::new(6, 2);
1155        let array = DecimalArray::new(buffer![125i32, 250, -375], dtype, Validity::NonNullable);
1156        let target = DType::Primitive(PType::F64, Nullability::NonNullable);
1157        let casted = array.into_array().cast(target.clone()).unwrap();
1158        assert_eq!(casted.dtype(), &target);
1159
1160        let mut ctx = SESSION.create_execution_ctx();
1161        let primitive = casted
1162            .execute::<Canonical>(&mut ctx)
1163            .unwrap()
1164            .into_primitive();
1165        assert_eq!(primitive.to_buffer::<f64>().as_ref(), &[1.25, 2.5, -3.75]);
1166    }
1167
1168    #[test]
1169    fn cast_decimal_f64_null() {
1170        let values = [Some(100i32), None, Some(-200)];
1171        let array = DecimalArray::from_option_iter(values, DecimalDType::new(6, 2));
1172        let target = DType::Primitive(PType::F64, Nullability::Nullable);
1173        let casted = array.into_array().cast(target.clone()).unwrap();
1174        assert_eq!(casted.dtype(), &target);
1175
1176        let mut ctx = SESSION.create_execution_ctx();
1177        let primitive = casted
1178            .execute::<Canonical>(&mut ctx)
1179            .unwrap()
1180            .into_primitive();
1181
1182        assert!(primitive.is_valid(0, &mut ctx).unwrap());
1183        assert!(!primitive.is_valid(1, &mut ctx).unwrap());
1184        assert!(primitive.is_valid(2, &mut ctx).unwrap());
1185
1186        assert_eq!(
1187            primitive.execute_scalar(0, &mut ctx).unwrap(),
1188            Scalar::from(1f64)
1189        );
1190        assert_eq!(
1191            primitive.execute_scalar(2, &mut ctx).unwrap(),
1192            Scalar::from(-2f64)
1193        );
1194    }
1195
1196    #[test]
1197    fn cast_decimal_f64_all_null() {
1198        let dtype = DecimalDType::new(6, 2);
1199        let buf = buffer![i32::MAX, i32::MIN, 12345];
1200        let array = DecimalArray::new(buf, dtype, Validity::AllInvalid);
1201        let target = DType::Primitive(PType::F64, Nullability::Nullable);
1202        let casted = array.into_array().cast(target.clone()).unwrap();
1203        assert_eq!(casted.dtype(), &target);
1204
1205        let mut ctx = SESSION.create_execution_ctx();
1206        assert_arrays_eq!(
1207            casted,
1208            PrimitiveArray::from_option_iter([None::<f64>; 3]),
1209            &mut ctx
1210        );
1211    }
1212}