Skip to main content

vortex_array/arrays/scalar_fn/
array.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::fmt::Display;
5use std::fmt::Formatter;
6
7use smallvec::SmallVec;
8use vortex_error::VortexExpect;
9use vortex_error::VortexResult;
10use vortex_error::vortex_bail;
11use vortex_error::vortex_ensure;
12
13use crate::ArrayRef;
14use crate::ArraySlots;
15use crate::array::Array;
16use crate::array::ArrayParts;
17use crate::array::TypedArrayRef;
18use crate::arrays::ScalarFn;
19use crate::dtype::DType;
20use crate::scalar_fn::ScalarFnRef;
21use crate::scalar_fn::fns::literal::Literal;
22
23// ScalarFnArray has a variable number of slots (one per child)
24
25#[derive(Clone, Debug)]
26pub struct ScalarFnData {
27    pub(super) scalar_fn: ScalarFnRef,
28}
29
30impl Display for ScalarFnData {
31    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
32        write!(f, "scalar_fn: {}", self.scalar_fn)
33    }
34}
35
36impl ScalarFnData {
37    /// Get the scalar function bound to this array.
38    #[allow(clippy::inline_always)]
39    #[inline(always)]
40    pub fn scalar_fn(&self) -> &ScalarFnRef {
41        &self.scalar_fn
42    }
43}
44
45pub trait ScalarFnArrayExt: TypedArrayRef<ScalarFn> {
46    fn scalar_fn(&self) -> &ScalarFnRef {
47        &self.scalar_fn
48    }
49
50    fn child_at(&self, idx: usize) -> &ArrayRef {
51        self.slots()[idx]
52            .as_ref()
53            .vortex_expect("ScalarFnArray child slot")
54    }
55
56    fn child_count(&self) -> usize {
57        self.slots().len()
58    }
59
60    fn nchildren(&self) -> usize {
61        self.child_count()
62    }
63
64    fn get_child(&self, idx: usize) -> &ArrayRef {
65        self.child_at(idx)
66    }
67
68    fn iter_children(&self) -> impl Iterator<Item = &ArrayRef> + '_ {
69        (0..self.child_count()).map(|idx| self.child_at(idx))
70    }
71
72    fn children(&self) -> Vec<ArrayRef> {
73        self.iter_children().cloned().collect()
74    }
75}
76impl<T: TypedArrayRef<ScalarFn>> ScalarFnArrayExt for T {}
77
78impl Array<ScalarFn> {
79    /// Create a new ScalarFnArray from a scalar function and its children.
80    pub fn try_new(
81        scalar_fn: ScalarFnRef,
82        children: impl IntoIterator<Item = ArrayRef>,
83    ) -> VortexResult<Self> {
84        let slots: ArraySlots = children.into_iter().map(Some).collect();
85        let len = Self::infer_len(&slots)?;
86        Self::try_new_from_slots(scalar_fn, slots, len)
87    }
88
89    /// Create a new ScalarFnArray from a scalar function, children, and an explicit length.
90    ///
91    /// This is needed for zero-child scalar functions and deserialization paths where there is no
92    /// child array to infer the length from.
93    pub fn try_new_with_len(
94        scalar_fn: ScalarFnRef,
95        children: impl IntoIterator<Item = ArrayRef>,
96        len: usize,
97    ) -> VortexResult<Self> {
98        let slots: ArraySlots = children.into_iter().map(Some).collect();
99        Self::try_new_from_slots(scalar_fn, slots, len)
100    }
101
102    #[inline]
103    fn try_new_from_slots(
104        scalar_fn: ScalarFnRef,
105        slots: ArraySlots,
106        len: usize,
107    ) -> VortexResult<Self> {
108        Self::validate_not_literal(&scalar_fn)?;
109        Self::validate_arity(&scalar_fn, slots.len())?;
110        Self::validate_children_len(&slots, len)?;
111
112        let arg_dtypes = Self::arg_dtypes(&slots);
113        let scalar_fn = scalar_fn.bind_options(&arg_dtypes)?;
114        let dtype = scalar_fn.return_dtype(&arg_dtypes)?;
115
116        Ok(unsafe { Self::new_from_validated_slots(scalar_fn, dtype, slots, len) })
117    }
118
119    /// # Safety
120    /// The caller must ensure arity and child lengths were validated and
121    /// "dtype" is scalar function's return dtype.
122    ///
123    /// This function is not inlined, so crates that construct scalar function arrays do not each
124    /// compile the `ScalarFn` array vtable.
125    unsafe fn new_from_validated_slots(
126        scalar_fn: ScalarFnRef,
127        dtype: DType,
128        slots: ArraySlots,
129        len: usize,
130    ) -> Self {
131        let vtable = ScalarFn { id: scalar_fn.id() };
132        let data = ScalarFnData { scalar_fn };
133        unsafe { Array::from_parts_unchecked(ArrayParts::new(vtable, dtype, len, data, slots)) }
134    }
135
136    #[inline]
137    fn arg_dtypes(slots: &[Option<ArrayRef>]) -> SmallVec<[DType; 4]> {
138        let mut arg_dtypes = SmallVec::with_capacity(slots.len());
139        for child in slots.iter().flatten() {
140            arg_dtypes.push(child.dtype().clone());
141        }
142        arg_dtypes
143    }
144
145    #[inline]
146    fn infer_len(slots: &[Option<ArrayRef>]) -> VortexResult<usize> {
147        let Some(child) = slots.first().and_then(Option::as_ref) else {
148            vortex_bail!("ScalarFnArray length cannot be inferred without children");
149        };
150        Ok(child.len())
151    }
152
153    /// A literal is always a [`ConstantArray`], so a ScalarFnArray must never wrap one.
154    ///
155    /// This is not a correctness requirement: a ScalarFnArray that wraps a literal executes
156    /// correctly. The check finds call sites that make a literal node instead of a constant. You
157    /// can relax it if a valid use for a literal ScalarFnArray occurs.
158    ///
159    /// [`ConstantArray`]: crate::arrays::ConstantArray
160    #[inline]
161    pub(super) fn validate_not_literal(scalar_fn: &ScalarFnRef) -> VortexResult<()> {
162        vortex_ensure!(
163            !scalar_fn.is::<Literal>(),
164            "ScalarFnArray cannot wrap a literal, use ConstantArray instead"
165        );
166        Ok(())
167    }
168
169    #[inline]
170    fn validate_arity(scalar_fn: &ScalarFnRef, child_count: usize) -> VortexResult<()> {
171        let arity = scalar_fn.signature().arity();
172        vortex_ensure!(
173            arity.matches(child_count),
174            "ScalarFnArray requires {arity} children, got {child_count}"
175        );
176        Ok(())
177    }
178
179    #[inline]
180    fn validate_children_len(slots: &[Option<ArrayRef>], len: usize) -> VortexResult<()> {
181        for child in slots.iter().flatten() {
182            vortex_ensure!(
183                child.len() == len,
184                "ScalarFnArray must have children equal to the array length"
185            );
186        }
187        Ok(())
188    }
189}