Skip to main content

vortex_array/arrays/primitive/array/
mod.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_buffer::Alignment;
9use vortex_buffer::Buffer;
10use vortex_buffer::BufferMut;
11use vortex_buffer::ByteBuffer;
12use vortex_buffer::ByteBufferMut;
13use vortex_error::VortexExpect;
14use vortex_error::VortexResult;
15use vortex_error::vortex_err;
16use vortex_error::vortex_panic;
17
18use crate::ArraySlots;
19use crate::ExecutionCtx;
20use crate::array::Array;
21use crate::array::ArrayParts;
22use crate::array::TypedArrayRef;
23use crate::arrays::BoolArray;
24use crate::arrays::Primitive;
25use crate::arrays::PrimitiveArray;
26use crate::dtype::DType;
27use crate::dtype::NativePType;
28use crate::dtype::Nullability;
29use crate::dtype::PType;
30use crate::match_each_native_ptype;
31use crate::validity::Validity;
32
33mod cast;
34mod conversion;
35mod patch;
36mod top_value;
37
38pub use patch::chunk_range;
39pub use patch::patch_chunk;
40
41use crate::ArrayRef;
42use crate::aggregate_fn::NumericalAggregateOpts;
43use crate::aggregate_fn::fns::min_max::min_max;
44use crate::array::child_to_validity;
45use crate::array::validity_to_child;
46use crate::array_slots;
47use crate::arrays::bool::BoolArrayExt;
48use crate::buffer::BufferHandle;
49use crate::builtins::ArrayBuiltins;
50
51#[array_slots(Primitive)]
52pub struct PrimitiveSlots {
53    /// The validity bitmap indicating which elements are non-null.
54    #[slot(0)]
55    pub validity: Option<ArrayRef>,
56}
57
58/// A primitive array that stores [native types][crate::dtype::NativePType] in a contiguous buffer
59/// of memory, along with an optional validity child.
60///
61/// This mirrors the Apache Arrow Primitive layout and can be converted into and out of one
62/// without allocations or copies.
63///
64/// The underlying buffer must be natively aligned to the primitive type they are representing.
65///
66/// Values are stored in their native representation with proper alignment.
67/// Null values still occupy space in the buffer but are marked invalid in the validity mask.
68///
69/// # Examples
70///
71/// ```
72/// # fn main() -> vortex_error::VortexResult<()> {
73/// use vortex_array::arrays::PrimitiveArray;
74/// use vortex_array::{VortexSessionExecute};
75/// use vortex_session::VortexSession;
76///
77/// // Create from iterator using FromIterator impl
78/// let array: PrimitiveArray = [1i32, 2, 3, 4, 5].into_iter().collect();
79///
80/// // Slice the array
81/// let sliced = array.slice(1..3)?;
82///
83/// // Access individual values
84/// let mut ctx = VortexSession::empty().create_execution_ctx();
85/// let value = sliced.execute_scalar(0, &mut ctx).unwrap();
86/// assert_eq!(value, 2i32.into());
87///
88/// # Ok(())
89/// # }
90/// ```
91#[derive(Clone, Debug)]
92pub struct PrimitiveData {
93    pub(super) ptype: PType,
94    pub(super) buffer: BufferHandle,
95}
96
97impl Display for PrimitiveData {
98    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
99        write!(f, "ptype: {}", self.ptype)
100    }
101}
102
103pub struct PrimitiveDataParts {
104    pub ptype: PType,
105    pub buffer: BufferHandle,
106    pub validity: Validity,
107}
108
109pub trait PrimitiveArrayExt: TypedArrayRef<Primitive> {
110    fn ptype(&self) -> PType {
111        match self.dtype() {
112            DType::Primitive(ptype, _) => *ptype,
113            _ => unreachable!("PrimitiveArrayExt requires a primitive dtype"),
114        }
115    }
116
117    fn nullability(&self) -> Nullability {
118        match self.dtype() {
119            DType::Primitive(_, nullability) => *nullability,
120            _ => unreachable!("PrimitiveArrayExt requires a primitive dtype"),
121        }
122    }
123
124    fn validity_child(&self) -> Option<&ArrayRef> {
125        self.slots()[PrimitiveSlots::VALIDITY].as_ref()
126    }
127
128    fn validity(&self) -> Validity {
129        child_to_validity(
130            self.slots()[PrimitiveSlots::VALIDITY].as_ref(),
131            self.nullability(),
132        )
133    }
134
135    fn buffer_handle(&self) -> &BufferHandle {
136        &self.buffer
137    }
138
139    fn reinterpret_cast(&self, ptype: PType) -> PrimitiveArray {
140        if self.ptype() == ptype {
141            return self.to_owned();
142        }
143
144        assert_eq!(
145            self.ptype().byte_width(),
146            ptype.byte_width(),
147            "can't reinterpret cast between integers of two different widths"
148        );
149
150        PrimitiveArray::from_buffer_handle(
151            self.buffer_handle().clone(),
152            ptype,
153            PrimitiveArrayExt::validity(self),
154        )
155    }
156
157    /// Narrow the array to the smallest possible integer type that can represent all values.
158    fn narrow(&self, ctx: &mut ExecutionCtx) -> VortexResult<PrimitiveArray> {
159        if !self.ptype().is_int() {
160            return Ok(self.to_owned());
161        }
162
163        let Some(min_max) = min_max(self.as_ref(), ctx, NumericalAggregateOpts::default())? else {
164            return Ok(PrimitiveArray::new(
165                Buffer::<u8>::zeroed(self.len()),
166                PrimitiveArrayExt::validity(self),
167            ));
168        };
169
170        // If we can't cast to i64, then leave the array as its original type.
171        // It's too big to downcast anyway.
172        let Ok(min) = min_max
173            .min
174            .cast(&PType::I64.into())
175            .and_then(|s| i64::try_from(&s))
176        else {
177            return Ok(self.to_owned());
178        };
179        let Ok(max) = min_max
180            .max
181            .cast(&PType::I64.into())
182            .and_then(|s| i64::try_from(&s))
183        else {
184            return Ok(self.to_owned());
185        };
186
187        let nullability = self.dtype().nullability();
188
189        if min < 0 || max < 0 {
190            // Signed
191            if min >= i8::MIN as i64 && max <= i8::MAX as i64 {
192                let result = self
193                    .as_ref()
194                    .cast(DType::Primitive(PType::I8, nullability))?
195                    .execute::<PrimitiveArray>(ctx)?;
196                return Ok(result);
197            }
198
199            if min >= i16::MIN as i64 && max <= i16::MAX as i64 {
200                let result = self
201                    .as_ref()
202                    .cast(DType::Primitive(PType::I16, nullability))?
203                    .execute::<PrimitiveArray>(ctx)?;
204                return Ok(result);
205            }
206
207            if min >= i32::MIN as i64 && max <= i32::MAX as i64 {
208                let result = self
209                    .as_ref()
210                    .cast(DType::Primitive(PType::I32, nullability))?
211                    .execute::<PrimitiveArray>(ctx)?;
212                return Ok(result);
213            }
214        } else {
215            // Unsigned
216            if max <= u8::MAX as i64 {
217                let result = self
218                    .as_ref()
219                    .cast(DType::Primitive(PType::U8, nullability))?
220                    .execute::<PrimitiveArray>(ctx)?;
221                return Ok(result);
222            }
223
224            if max <= u16::MAX as i64 {
225                let result = self
226                    .as_ref()
227                    .cast(DType::Primitive(PType::U16, nullability))?
228                    .execute::<PrimitiveArray>(ctx)?;
229                return Ok(result);
230            }
231
232            if max <= u32::MAX as i64 {
233                let result = self
234                    .as_ref()
235                    .cast(DType::Primitive(PType::U32, nullability))?
236                    .execute::<PrimitiveArray>(ctx)?;
237                return Ok(result);
238            }
239        }
240
241        Ok(self.to_owned())
242    }
243}
244impl<T: TypedArrayRef<Primitive>> PrimitiveArrayExt for T {}
245
246// TODO(connor): There are a lot of places where we could be using `new_unchecked` in the codebase.
247impl PrimitiveData {
248    /// Build the slots vector for this array.
249    pub(super) fn make_slots(validity: &Validity, len: usize) -> ArraySlots {
250        smallvec![validity_to_child(validity, len)]
251    }
252
253    /// Create a new array from a buffer handle.
254    ///
255    /// # Safety
256    ///
257    /// Should ensure that the provided BufferHandle points at sufficiently large region of aligned
258    /// memory to hold the `ptype` values.
259    pub unsafe fn new_unchecked_from_handle(
260        handle: BufferHandle,
261        ptype: PType,
262        _validity: Validity,
263    ) -> Self {
264        Self {
265            ptype,
266            buffer: handle,
267        }
268    }
269
270    /// Creates a new `PrimitiveArray`.
271    ///
272    /// # Panics
273    ///
274    /// Panics if the provided components do not satisfy the invariants documented
275    /// in `PrimitiveArray::new_unchecked`.
276    pub fn new<T: NativePType>(buffer: impl Into<Buffer<T>>, validity: Validity) -> Self {
277        let buffer = buffer.into();
278        Self::try_new(buffer, validity).vortex_expect("PrimitiveArray construction failed")
279    }
280
281    /// Constructs a new `PrimitiveArray`.
282    ///
283    /// See `PrimitiveArray::new_unchecked` for more information.
284    ///
285    /// # Errors
286    ///
287    /// Returns an error if the provided components do not satisfy the invariants documented in
288    /// `PrimitiveArray::new_unchecked`.
289    #[inline]
290    pub fn try_new<T: NativePType>(buffer: Buffer<T>, validity: Validity) -> VortexResult<Self> {
291        Self::validate(&buffer, &validity)?;
292
293        // SAFETY: validate ensures all invariants are met.
294        Ok(unsafe { Self::new_unchecked(buffer, validity) })
295    }
296
297    /// Creates a new `PrimitiveArray` without validation from these components:
298    ///
299    /// * `buffer` is a typed buffer containing the primitive values.
300    /// * `validity` holds the null values.
301    ///
302    /// # Safety
303    ///
304    /// The caller must ensure all of the following invariants are satisfied:
305    ///
306    /// ## Validity Requirements
307    ///
308    /// - If `validity` is [`Validity::Array`], its length must exactly equal `buffer.len()`.
309    #[inline]
310    pub unsafe fn new_unchecked<T: NativePType>(buffer: Buffer<T>, _validity: Validity) -> Self {
311        #[cfg(debug_assertions)]
312        Self::validate(&buffer, &_validity)
313            .vortex_expect("[Debug Assertion]: Invalid `PrimitiveArray` parameters");
314
315        Self {
316            ptype: T::PTYPE,
317            buffer: BufferHandle::new_host(buffer.into_byte_buffer()),
318        }
319    }
320
321    /// Validates the components that would be used to create a `PrimitiveArray`.
322    ///
323    /// This function checks all the invariants required by `PrimitiveArray::new_unchecked`.
324    #[inline]
325    pub fn validate<T: NativePType>(buffer: &Buffer<T>, validity: &Validity) -> VortexResult<()> {
326        if let Some(len) = validity.maybe_len()
327            && buffer.len() != len
328        {
329            return Err(vortex_err!(
330                "Buffer and validity length mismatch: buffer={}, validity={}",
331                buffer.len(),
332                len
333            ));
334        }
335        Ok(())
336    }
337
338    pub fn empty<T: NativePType>(nullability: Nullability) -> Self {
339        Self::new(Buffer::<T>::empty(), nullability.into())
340    }
341}
342
343impl Array<Primitive> {
344    pub fn empty<T: NativePType>(nullability: Nullability) -> Self {
345        let dtype = DType::Primitive(T::PTYPE, nullability);
346        let len = 0;
347        let data = PrimitiveData::empty::<T>(nullability);
348        let slots = PrimitiveData::make_slots(&Validity::from(nullability), len);
349        unsafe {
350            Self::from_primitive_parts_unchecked(ArrayParts::new(
351                Primitive, dtype, len, data, slots,
352            ))
353        }
354    }
355
356    /// Creates a new `PrimitiveArray`.
357    ///
358    /// # Panics
359    ///
360    /// Panics if the provided components do not satisfy the invariants.
361    pub fn new<T: NativePType>(buffer: impl Into<Buffer<T>>, validity: Validity) -> Self {
362        let buffer = buffer.into();
363        let dtype = DType::Primitive(T::PTYPE, validity.nullability());
364        let len = buffer.len();
365        let slots = PrimitiveData::make_slots(&validity, len);
366        let data = PrimitiveData::new(buffer, validity);
367        unsafe {
368            Self::from_primitive_parts_unchecked(ArrayParts::new(
369                Primitive, dtype, len, data, slots,
370            ))
371        }
372    }
373
374    /// Constructs a new `PrimitiveArray`.
375    pub fn try_new<T: NativePType>(buffer: Buffer<T>, validity: Validity) -> VortexResult<Self> {
376        let dtype = DType::Primitive(T::PTYPE, validity.nullability());
377        let len = buffer.len();
378        let slots = PrimitiveData::make_slots(&validity, len);
379        let data = PrimitiveData::try_new(buffer, validity)?;
380        Ok(unsafe {
381            Self::from_primitive_parts_unchecked(ArrayParts::new(
382                Primitive, dtype, len, data, slots,
383            ))
384        })
385    }
386
387    /// Creates a new `PrimitiveArray` without validation.
388    ///
389    /// # Safety
390    ///
391    /// See [`PrimitiveData::new_unchecked`].
392    pub unsafe fn new_unchecked<T: NativePType>(buffer: Buffer<T>, validity: Validity) -> Self {
393        let dtype = DType::Primitive(T::PTYPE, validity.nullability());
394        let len = buffer.len();
395        let slots = PrimitiveData::make_slots(&validity, len);
396        let data = unsafe { PrimitiveData::new_unchecked(buffer, validity) };
397        unsafe {
398            Self::from_primitive_parts_unchecked(ArrayParts::new(
399                Primitive, dtype, len, data, slots,
400            ))
401        }
402    }
403
404    /// Creates the array from parts without validation.
405    ///
406    /// The generic constructors call this function. It is not generic, so crates that call those
407    /// constructors do not each compile the `Primitive` array vtable.
408    ///
409    /// # Safety
410    ///
411    /// The parts must be logically consistent.
412    unsafe fn from_primitive_parts_unchecked(parts: ArrayParts<Primitive>) -> Self {
413        unsafe { Array::from_parts_unchecked(parts) }
414    }
415
416    /// Create a new array from a buffer handle.
417    ///
418    /// # Safety
419    ///
420    /// See [`PrimitiveData::new_unchecked_from_handle`].
421    pub unsafe fn new_unchecked_from_handle(
422        handle: BufferHandle,
423        ptype: PType,
424        validity: Validity,
425    ) -> Self {
426        let dtype = DType::Primitive(ptype, validity.nullability());
427        let len = handle.len() / ptype.byte_width();
428        let slots = PrimitiveData::make_slots(&validity, len);
429        let data = unsafe { PrimitiveData::new_unchecked_from_handle(handle, ptype, validity) };
430        unsafe { Array::from_parts_unchecked(ArrayParts::new(Primitive, dtype, len, data, slots)) }
431    }
432
433    /// Creates a new `PrimitiveArray` from a [`BufferHandle`].
434    pub fn from_buffer_handle(handle: BufferHandle, ptype: PType, validity: Validity) -> Self {
435        let dtype = DType::Primitive(ptype, validity.nullability());
436        let len = handle.len() / ptype.byte_width();
437        let slots = PrimitiveData::make_slots(&validity, len);
438        let data = PrimitiveData::from_buffer_handle(handle, ptype, validity);
439        Array::try_from_parts(ArrayParts::new(Primitive, dtype, len, data, slots))
440            .vortex_expect("PrimitiveData is always valid")
441    }
442
443    /// Creates a new `PrimitiveArray` from a [`ByteBuffer`].
444    pub fn from_byte_buffer(buffer: ByteBuffer, ptype: PType, validity: Validity) -> Self {
445        let dtype = DType::Primitive(ptype, validity.nullability());
446        let len = buffer.len() / ptype.byte_width();
447        let slots = PrimitiveData::make_slots(&validity, len);
448        let data = PrimitiveData::from_byte_buffer(buffer, ptype, validity);
449        unsafe { Array::from_parts_unchecked(ArrayParts::new(Primitive, dtype, len, data, slots)) }
450    }
451
452    /// Create a PrimitiveArray from a byte buffer containing only the valid elements.
453    pub fn from_values_byte_buffer(
454        valid_elems_buffer: ByteBuffer,
455        ptype: PType,
456        validity: Validity,
457        n_rows: usize,
458        ctx: &mut ExecutionCtx,
459    ) -> Self {
460        let dtype = DType::Primitive(ptype, validity.nullability());
461        let len = n_rows;
462        let slots = PrimitiveData::make_slots(&validity, len);
463        let data = PrimitiveData::from_values_byte_buffer(
464            valid_elems_buffer,
465            ptype,
466            validity,
467            n_rows,
468            ctx,
469        );
470        unsafe { Array::from_parts_unchecked(ArrayParts::new(Primitive, dtype, len, data, slots)) }
471    }
472
473    /// Validates the components that would be used to create a `PrimitiveArray`.
474    pub fn validate<T: NativePType>(buffer: &Buffer<T>, validity: &Validity) -> VortexResult<()> {
475        PrimitiveData::validate(buffer, validity)
476    }
477
478    pub fn into_data_parts(self) -> PrimitiveDataParts {
479        let validity = PrimitiveArrayExt::validity(&self);
480        let ptype = PrimitiveArrayExt::ptype(&self);
481        let data = self.into_data();
482        PrimitiveDataParts {
483            ptype,
484            buffer: data.buffer,
485            validity,
486        }
487    }
488}
489
490impl PrimitiveData {
491    pub fn len(&self) -> usize {
492        self.buffer.len() / self.ptype.byte_width()
493    }
494
495    /// Returns `true` if the array is empty.
496    pub fn is_empty(&self) -> bool {
497        self.buffer.is_empty()
498    }
499
500    pub fn ptype(&self) -> PType {
501        self.ptype
502    }
503
504    /// Get access to the buffer handle backing the array.
505    pub fn buffer_handle(&self) -> &BufferHandle {
506        &self.buffer
507    }
508
509    pub fn from_buffer_handle(handle: BufferHandle, ptype: PType, _validity: Validity) -> Self {
510        Self {
511            ptype,
512            buffer: handle,
513        }
514    }
515
516    pub fn from_byte_buffer(buffer: ByteBuffer, ptype: PType, validity: Validity) -> Self {
517        match_each_native_ptype!(ptype, |T| {
518            Self::new::<T>(Buffer::from_byte_buffer(buffer), validity)
519        })
520    }
521
522    /// Create a PrimitiveArray from a byte buffer containing only the valid elements.
523    pub fn from_values_byte_buffer(
524        valid_elems_buffer: ByteBuffer,
525        ptype: PType,
526        validity: Validity,
527        n_rows: usize,
528        ctx: &mut ExecutionCtx,
529    ) -> Self {
530        let byte_width = ptype.byte_width();
531        let alignment = Alignment::new(byte_width);
532        let buffer = match &validity {
533            Validity::AllValid | Validity::NonNullable => valid_elems_buffer.aligned(alignment),
534            Validity::AllInvalid => ByteBuffer::zeroed_aligned(n_rows * byte_width, alignment),
535            Validity::Array(is_valid) => {
536                let bool_array = is_valid
537                    .clone()
538                    .execute::<BoolArray>(ctx)
539                    .vortex_expect("must be a bool array");
540                let bool_buffer = bool_array.bit_buffer_view();
541                let mut bytes = ByteBufferMut::zeroed_aligned(n_rows * byte_width, alignment);
542                for (i, valid_i) in bool_buffer.set_indices().enumerate() {
543                    bytes[valid_i * byte_width..(valid_i + 1) * byte_width]
544                        .copy_from_slice(&valid_elems_buffer[i * byte_width..(i + 1) * byte_width])
545                }
546                bytes.freeze()
547            }
548        };
549
550        Self::from_byte_buffer(buffer, ptype, validity)
551    }
552
553    /// Get a buffer in host memory holding all the values.
554    ///
555    /// NOTE: some values may be nonsense if the validity buffer indicates that the value is null.
556    pub fn to_buffer<T: NativePType>(&self) -> Buffer<T> {
557        if T::PTYPE != self.ptype() {
558            vortex_panic!(
559                "Attempted to get buffer of type {} from array of type {}",
560                T::PTYPE,
561                self.ptype()
562            )
563        }
564        Buffer::from_byte_buffer(self.buffer_handle().to_host_sync())
565    }
566
567    /// Consume the array and get a host Buffer containing the data values.
568    pub fn into_buffer<T: NativePType>(self) -> Buffer<T> {
569        if T::PTYPE != self.ptype() {
570            vortex_panic!(
571                "Attempted to get buffer of type {} from array of type {}",
572                T::PTYPE,
573                self.ptype()
574            )
575        }
576        Buffer::from_byte_buffer(self.buffer.into_host_sync())
577    }
578
579    /// Extract a mutable buffer from the PrimitiveData. Attempts to do this with zero-copy
580    /// if the buffer is uniquely owned, otherwise will make a copy.
581    pub fn into_buffer_mut<T: NativePType>(self) -> BufferMut<T> {
582        self.try_into_buffer_mut()
583            .unwrap_or_else(|buffer| BufferMut::<T>::copy_from(&buffer))
584    }
585
586    /// Try to extract a mutable buffer from the PrimitiveData with zero copy.
587    ///
588    /// # Panic
589    /// If the buffer is not of type T this will panic
590    pub fn try_into_buffer_mut<T: NativePType>(self) -> Result<BufferMut<T>, Buffer<T>> {
591        if T::PTYPE != self.ptype() {
592            vortex_panic!(
593                "Attempted to get buffer_mut of type {} from array of type {}",
594                T::PTYPE,
595                self.ptype()
596            )
597        }
598        let buffer = Buffer::<T>::from_byte_buffer(self.buffer.into_host_sync());
599        buffer.try_into_mut()
600    }
601}