vortex_array/scalar_fn/fns/cast/kernel.rs
1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use vortex_error::VortexResult;
5
6use crate::ArrayRef;
7use crate::ExecutionCtx;
8use crate::array::ArrayView;
9use crate::array::VTable;
10use crate::arrays::scalar_fn::ExactScalarFn;
11use crate::arrays::scalar_fn::ScalarFnArrayView;
12use crate::dtype::DType;
13use crate::kernel::ExecuteParentKernel;
14use crate::matcher::Matcher;
15use crate::optimizer::rules::ArrayParentReduceRule;
16use crate::scalar_fn::fns::cast::Cast;
17
18/// Reduce rule for cast: restructure the array without reading buffers.
19///
20/// Encodings implement this to push cast operations through their structure.
21/// For example, RunEnd pushes cast down to its values array, ZigZag transforms
22/// the target dtype to unsigned and pushes to its encoded array.
23///
24/// Returns `Ok(None)` if the rule doesn't apply to this array/dtype combination.
25///
26/// # Nullability
27///
28/// A cast to a non-nullable dtype **must** fail when the array has a null row. A rule cannot
29/// execute, so it handles this in one of two ways:
30///
31/// - It builds a new [`Validity`], as [`Primitive`] does. It **must** return `Ok(None)` when
32/// [`Validity::trivially_cast_nullability`] does, and the encoding implements [`CastKernel`] for
33/// that case.
34/// - It pushes the cast into the children that hold its validity, as FoR does, and the casts of
35/// those children check the nulls. Every null in those children **must** reach a row of the
36/// array. The values of [`Dict`] break this with nulls that no code references.
37///
38/// [`test_cast_conformance`] checks both forms with a partially valid array.
39///
40/// [`Primitive`]: crate::arrays::Primitive
41/// [`Dict`]: crate::arrays::Dict
42/// [`Validity`]: crate::validity::Validity
43/// [`Validity::trivially_cast_nullability`]: crate::validity::Validity::trivially_cast_nullability
44/// [`test_cast_conformance`]: crate::compute::conformance::cast::test_cast_conformance
45pub trait CastReduce: VTable {
46 fn cast(array: ArrayView<'_, Self>, dtype: &DType) -> VortexResult<Option<ArrayRef>>;
47}
48
49/// Execute kernel for cast: perform the actual value conversion, potentially reading buffers.
50///
51/// Canonical array types implement this to do the real type conversion work.
52/// For example, PrimitiveArray converts numeric values between types.
53///
54/// Returns `Ok(None)` if this kernel cannot handle the given dtype conversion.
55pub trait CastKernel: VTable {
56 fn cast(
57 array: ArrayView<'_, Self>,
58 dtype: &DType,
59 ctx: &mut ExecutionCtx,
60 ) -> VortexResult<Option<ArrayRef>>;
61}
62
63/// Adapts a [`CastReduce`] impl into an [`ArrayParentReduceRule`] for `ScalarFnArray(Cast, ...)`.
64#[derive(Default, Debug)]
65pub struct CastReduceAdaptor<V>(pub V);
66
67impl<V> ArrayParentReduceRule<V> for CastReduceAdaptor<V>
68where
69 V: CastReduce,
70{
71 type Parent = ExactScalarFn<Cast>;
72
73 fn reduce_parent(
74 &self,
75 array: ArrayView<'_, V>,
76 parent: ScalarFnArrayView<'_, Cast>,
77 _child_idx: usize,
78 ) -> VortexResult<Option<ArrayRef>> {
79 let dtype = parent.options;
80 if array.dtype() == dtype {
81 return Ok(Some(array.array().clone()));
82 }
83 <V as CastReduce>::cast(array, dtype)
84 }
85}
86
87/// Adapts a [`CastKernel`] impl into an [`ExecuteParentKernel`] for `ScalarFnArray(Cast, ...)`.
88#[derive(Default, Debug)]
89pub struct CastExecuteAdaptor<V>(pub V);
90
91impl<V> ExecuteParentKernel<V> for CastExecuteAdaptor<V>
92where
93 V: CastKernel,
94{
95 type Parent = ExactScalarFn<Cast>;
96
97 fn execute_parent(
98 &self,
99 array: ArrayView<'_, V>,
100 parent: <Self::Parent as Matcher>::Match<'_>,
101 _child_idx: usize,
102 ctx: &mut ExecutionCtx,
103 ) -> VortexResult<Option<ArrayRef>> {
104 let dtype = parent.options;
105 if array.dtype() == dtype {
106 return Ok(Some(array.array().clone()));
107 }
108 <V as CastKernel>::cast(array, dtype, ctx)
109 }
110}