Skip to main content

vortex_array/builders/
primitive.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::any::Any;
5use std::mem::MaybeUninit;
6
7use vortex_buffer::BufferAllocatorRef;
8use vortex_buffer::BufferMut;
9use vortex_error::VortexExpect;
10use vortex_error::VortexResult;
11use vortex_error::vortex_ensure_eq;
12use vortex_mask::Mask;
13
14use crate::ArrayRef;
15use crate::ExecutionCtx;
16use crate::IntoArray;
17use crate::arrays::PrimitiveArray;
18use crate::builders::ArrayBuilder;
19use crate::builders::DEFAULT_BUILDER_CAPACITY;
20use crate::builders::LazyBitBufferBuilder;
21use crate::canonical::Canonical;
22use crate::dtype::DType;
23use crate::dtype::NativePType;
24use crate::dtype::Nullability;
25use crate::scalar::Scalar;
26
27/// The builder for building a [`PrimitiveArray`], parametrized by the `PType`.
28pub struct PrimitiveBuilder<T> {
29    dtype: DType,
30    values: BufferMut<T>,
31    nulls: LazyBitBufferBuilder,
32}
33
34impl<T: NativePType> PrimitiveBuilder<T> {
35    /// Creates a new `PrimitiveBuilder` with a capacity of [`DEFAULT_BUILDER_CAPACITY`].
36    #[deprecated(note = "use `new_in` with an explicit allocator")]
37    pub fn new(nullability: Nullability) -> Self {
38        Self::new_in(nullability, BufferAllocatorRef::static_ref())
39    }
40
41    /// Creates a new `PrimitiveBuilder` with the default capacity using `allocator`.
42    pub fn new_in(nullability: Nullability, allocator: &BufferAllocatorRef) -> Self {
43        Self::with_capacity_in(nullability, DEFAULT_BUILDER_CAPACITY, allocator)
44    }
45
46    /// Creates a new `PrimitiveBuilder` with the given `capacity`.
47    #[deprecated(note = "use `with_capacity_in` with an explicit allocator")]
48    pub fn with_capacity(nullability: Nullability, capacity: usize) -> Self {
49        Self::with_capacity_in(nullability, capacity, BufferAllocatorRef::static_ref())
50    }
51
52    /// Creates a new `PrimitiveBuilder` with `capacity` using `allocator`.
53    pub fn with_capacity_in(
54        nullability: Nullability,
55        capacity: usize,
56        allocator: &BufferAllocatorRef,
57    ) -> Self {
58        Self {
59            values: BufferMut::with_capacity_in(capacity, allocator.clone()),
60            nulls: LazyBitBufferBuilder::new(capacity, allocator.clone()),
61            dtype: DType::Primitive(T::PTYPE, nullability),
62        }
63    }
64
65    /// Appends a primitive `value` to the builder.
66    pub fn append_value(&mut self, value: T) {
67        self.values.push(value);
68        self.nulls.append_non_null();
69    }
70
71    /// Appends `n` copies of `value` as non-null entries, directly writing into the buffer.
72    pub fn append_n_values(&mut self, value: T, n: usize) {
73        self.values.push_n(value, n);
74        self.nulls.append_n_non_nulls(n);
75    }
76
77    /// Returns the raw primitive values in this builder as a slice.
78    pub fn values(&self) -> &[T] {
79        self.values.as_ref()
80    }
81
82    /// Returns the raw primitive values in this builder as a mutable slice.
83    pub fn values_mut(&mut self) -> &mut [T] {
84        self.values.as_mut()
85    }
86
87    /// Create a new handle to the next `len` uninitialized values in the builder.
88    ///
89    /// All reads/writes through the handle to the values buffer or the validity buffer will operate
90    /// on indices relative to the start of the range.
91    ///
92    /// # Panics
93    ///
94    /// Panics if `len` is 0 or if the current length of the builder plus `len` would exceed the
95    /// capacity of the builder's memory.
96    ///
97    /// ## Example
98    ///
99    /// ```
100    /// use std::mem::MaybeUninit;
101    /// use vortex_array::builders::{ArrayBuilder, PrimitiveBuilder};
102    /// use vortex_array::dtype::Nullability;
103    /// use vortex_array::memory::BufferAllocatorRef;
104    ///
105    /// // Create a new builder.
106    /// let mut builder: PrimitiveBuilder<i32> =
107    ///     PrimitiveBuilder::with_capacity_in(Nullability::NonNullable, 5, BufferAllocatorRef::static_ref());
108    ///
109    /// // Populate the values.
110    /// let mut uninit_range = builder.uninit_range(5);
111    /// uninit_range.copy_from_slice(0, &[0, 1, 2, 3, 4]);
112    ///
113    /// // SAFETY: We have initialized all 5 values in the range, and since the array builder is
114    /// // non-nullable, we don't need to set any null bits.
115    /// unsafe { uninit_range.finish(); }
116    ///
117    /// let built = builder.finish_into_primitive();
118    ///
119    /// assert_eq!(built.as_slice::<i32>(), &[0i32, 1, 2, 3, 4]);
120    /// ```
121    pub fn uninit_range(&mut self, len: usize) -> UninitRange<'_, T> {
122        assert_ne!(0, len, "cannot create an uninit range of length 0");
123
124        let current_len = self.values.len();
125        assert!(
126            current_len + len <= self.values.capacity(),
127            "uninit_range of len {len} exceeds builder with length {} and capacity {}",
128            current_len,
129            self.values.capacity()
130        );
131
132        UninitRange { len, builder: self }
133    }
134
135    /// Finishes the builder directly into a [`PrimitiveArray`].
136    pub fn finish_into_primitive(&mut self) -> PrimitiveArray {
137        let validity = self
138            .nulls
139            .finish_with_nullability(self.dtype().nullability());
140
141        let values = self.values.take().freeze();
142        PrimitiveArray::new(values, validity)
143    }
144
145    /// Extends the primitive array with an iterator.
146    pub fn extend_with_iterator(&mut self, iter: impl IntoIterator<Item = T>, mask: &Mask) {
147        self.values.extend(iter);
148        self.nulls.append_validity_mask(mask);
149    }
150
151    pub(crate) fn append_primitive_array(
152        &mut self,
153        array: &PrimitiveArray,
154        ctx: &mut ExecutionCtx,
155    ) -> VortexResult<()> {
156        debug_assert_eq!(
157            array.ptype(),
158            T::PTYPE,
159            "Cannot append primitive array with different ptype"
160        );
161
162        self.values.extend_from_slice(array.as_slice::<T>());
163        self.nulls.append_validity_mask(
164            &array
165                .as_ref()
166                .validity()
167                .vortex_expect("validity_mask")
168                .execute_mask(array.as_ref().len(), ctx)?,
169        );
170        Ok(())
171    }
172}
173
174impl<T: NativePType> ArrayBuilder for PrimitiveBuilder<T> {
175    fn as_any(&self) -> &dyn Any {
176        self
177    }
178
179    fn as_any_mut(&mut self) -> &mut dyn Any {
180        self
181    }
182
183    fn dtype(&self) -> &DType {
184        &self.dtype
185    }
186
187    fn len(&self) -> usize {
188        self.values.len()
189    }
190
191    fn append_zeros(&mut self, n: usize) {
192        self.values.push_n(T::default(), n);
193        self.nulls.append_n_non_nulls(n);
194    }
195
196    unsafe fn append_nulls_unchecked(&mut self, n: usize) {
197        self.values.push_n(T::default(), n);
198        self.nulls.append_n_nulls(n);
199    }
200
201    fn append_scalar(&mut self, scalar: &Scalar) -> VortexResult<()> {
202        vortex_ensure_eq!(
203            scalar.dtype(),
204            self.dtype(),
205            "PrimitiveBuilder received a scalar with the wrong dtype"
206        );
207
208        if let Some(pv) = scalar.as_primitive().pvalue() {
209            self.append_value(pv.cast::<T>()?)
210        } else {
211            self.append_null()
212        }
213
214        Ok(())
215    }
216
217    fn reserve_exact(&mut self, additional: usize) {
218        self.values.reserve(additional);
219        self.nulls.reserve_exact(additional);
220    }
221
222    fn finish(&mut self) -> ArrayRef {
223        self.finish_into_primitive().into_array()
224    }
225
226    fn finish_into_canonical(&mut self, _ctx: &mut ExecutionCtx) -> Canonical {
227        Canonical::Primitive(self.finish_into_primitive())
228    }
229}
230
231/// A range of uninitialized values in the primitive builder that can be filled.
232pub struct UninitRange<'a, T> {
233    /// The length of the uninitialized range.
234    ///
235    /// This is guaranteed to be within the memory capacity of the builder.
236    len: usize,
237
238    /// A mutable reference to the builder.
239    ///
240    /// Since this is a mutable reference, we can guarantee that nothing else can modify the builder
241    /// while this `UninitRange` exists.
242    builder: &'a mut PrimitiveBuilder<T>,
243}
244
245impl<T> UninitRange<'_, T> {
246    /// Returns the length of this uninitialized range.
247    #[inline]
248    pub fn len(&self) -> usize {
249        self.len
250    }
251
252    /// Returns true if this range has zero length.
253    #[inline]
254    pub fn is_empty(&self) -> bool {
255        self.len == 0
256    }
257
258    /// Set a value at the given index within this range.
259    ///
260    /// # Panics
261    ///
262    /// Panics if the index is out of bounds.
263    #[inline]
264    pub fn set_value(&mut self, index: usize, value: T) {
265        assert!(index < self.len, "index out of bounds");
266        let spare = self.builder.values.spare_capacity_mut();
267        spare[index] = MaybeUninit::new(value);
268    }
269
270    /// Append a [`Mask`] to this builder's null buffer.
271    ///
272    /// # Panics
273    ///
274    /// Panics if the mask length is not equal to the the length of the current `UninitRange`.
275    ///
276    /// # Safety
277    ///
278    /// - The caller must ensure that they safely initialize `mask.len()` primitive values via
279    ///   [`UninitRange::copy_from_slice`].
280    /// - The caller must also ensure that they only call this method once.
281    pub unsafe fn append_mask(&mut self, mask: &Mask) {
282        assert_eq!(
283            mask.len(),
284            self.len,
285            "Tried to append a mask to an `UninitRange` that was beyond the allowed range"
286        );
287
288        // TODO(connor): Ideally, we would call this function `set_mask` and directly set all of the
289        // bits (so that we can call this multiple times), but the underlying `BooleanBuffer` does
290        // not have an easy way to do this correctly.
291
292        self.builder.nulls.append_validity_mask(mask);
293    }
294
295    /// Set a validity bit at the given index.
296    ///
297    /// The index is relative to the start of this range (not relative to the values already in the
298    /// builder).
299    ///
300    /// Note that this will have no effect if the builder is non-nullable.
301    pub fn set_validity_bit(&mut self, index: usize, v: bool) {
302        assert!(index < self.len, "set_bit index out of bounds");
303        // Note that this won't panic because we can only create an `UninitRange` within the
304        // capacity of the builder (it will not automatically resize).
305        let absolute_index = self.builder.values.len() + index;
306        self.builder.nulls.set_bit(absolute_index, v);
307    }
308
309    /// Set values from an initialized range.
310    ///
311    /// Note that the input `offset` should be an offset relative to the local `UninitRange`, not
312    /// the entire `PrimitiveBuilder`.
313    pub fn copy_from_slice(&mut self, local_offset: usize, src: &[T])
314    where
315        T: Copy,
316    {
317        debug_assert!(
318            local_offset + src.len() <= self.len,
319            "tried to copy a slice into a `UninitRange` past its boundary"
320        );
321
322        // Note: spare_capacity_mut() returns the spare capacity starting from the current length,
323        // so we just use local_offset directly.
324        let dst =
325            &mut self.builder.values.spare_capacity_mut()[local_offset..local_offset + src.len()];
326        dst.write_copy_of_slice(src);
327    }
328
329    /// Get a mutable slice of uninitialized memory at the specified offset within this range.
330    ///
331    /// Note that the offsets are relative to this local range, not to the values already in the
332    /// builder.
333    ///
334    /// # Safety
335    ///
336    /// The caller must ensure that they properly initialize the returned memory before calling
337    /// `finish()` on this range.
338    ///
339    /// # Panics
340    ///
341    /// Panics if `offset + len` exceeds the range bounds.
342    pub unsafe fn slice_uninit_mut(&mut self, offset: usize, len: usize) -> &mut [MaybeUninit<T>] {
343        assert!(
344            offset + len <= self.len,
345            "slice_uninit_mut: offset {} + len {} exceeds range length {}",
346            offset,
347            len,
348            self.len
349        );
350        &mut self.builder.values.spare_capacity_mut()[offset..offset + len]
351    }
352
353    /// Finish building this range, marking it as initialized and advancing the length of the
354    /// underlying values buffer.
355    ///
356    /// # Safety
357    ///
358    /// The caller must ensure that they have safely initialized all `len` values via
359    /// [`copy_from_slice()`] or [`set_value()`], as well as correctly set all of the null bits via
360    /// [`set_validity_bit()`] or [`append_mask()`] if the builder is nullable.
361    ///
362    /// [`copy_from_slice()`]: UninitRange::copy_from_slice
363    /// [`set_value()`]: UninitRange::set_value
364    /// [`set_validity_bit()`]: UninitRange::set_validity_bit
365    /// [`append_mask()`]: UninitRange::append_mask
366    pub unsafe fn finish(self) {
367        // SAFETY: constructor enforces that current length + len does not exceed the capacity of the array.
368        let new_len = self.builder.values.len() + self.len;
369        unsafe { self.builder.values.set_len(new_len) };
370    }
371}
372
373#[cfg(test)]
374mod tests {
375    use std::sync::LazyLock;
376
377    use vortex_error::VortexExpect;
378    use vortex_session::VortexSession;
379
380    use super::*;
381    use crate::VortexSessionExecute;
382    use crate::assert_arrays_eq;
383
384    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
385
386    /// REGRESSION TEST: This test verifies that multiple sequential ranges have correct offsets.
387    ///
388    /// This would have caught the `Deref` bug where it always returned from the start of the
389    /// buffer.
390    #[test]
391    fn test_multiple_uninit_ranges_correct_offsets() {
392        let mut ctx = SESSION.create_execution_ctx();
393        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
394            Nullability::NonNullable,
395            10,
396            BufferAllocatorRef::static_ref(),
397        );
398
399        // First range.
400        let mut range1 = builder.uninit_range(3);
401        range1.copy_from_slice(0, &[1, 2, 3]);
402
403        // SAFETY: We initialized all 3 values.
404        unsafe {
405            range1.finish();
406        }
407
408        // Verify the builder now has these values.
409        assert_eq!(builder.values(), &[1, 2, 3]);
410
411        // Second range - this would fail with the old Deref implementation.
412        let mut range2 = builder.uninit_range(2);
413
414        // Set values using copy_from_slice.
415        range2.copy_from_slice(0, &[4, 5]);
416
417        // SAFETY: We initialized both values.
418        unsafe {
419            range2.finish();
420        }
421
422        // Verify the builder now has all 5 values.
423        assert_eq!(builder.values(), &[1, 2, 3, 4, 5]);
424
425        let array = builder.finish_into_primitive();
426        assert_arrays_eq!(
427            array,
428            PrimitiveArray::from_iter([1i32, 2, 3, 4, 5]),
429            &mut ctx
430        );
431    }
432
433    /// REGRESSION TEST: This test verifies that `append_mask` was correctly moved from
434    /// `PrimitiveBuilder` to `UninitRange`.
435    ///
436    /// The old API had `append_mask` on the builder, which was confusing when used with ranges.
437    /// This test ensures the new API works correctly.
438    #[test]
439    fn test_append_mask_on_uninit_range() {
440        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
441            Nullability::Nullable,
442            5,
443            BufferAllocatorRef::static_ref(),
444        );
445        let mut range = builder.uninit_range(3);
446
447        // Create a mask for 3 values.
448        let mask = Mask::from_iter([true, false, true]);
449
450        // SAFETY: We're about to initialize the values.
451        unsafe {
452            range.append_mask(&mask);
453        }
454
455        // Initialize the values.
456        range.copy_from_slice(0, &[10, 20, 30]);
457
458        // SAFETY: We've initialized all values and set the mask.
459        unsafe {
460            range.finish();
461        }
462
463        let array = builder.finish_into_primitive();
464        assert_eq!(array.len(), 3);
465        // Check validity using scalar_at - nulls will return is_null() = true.
466        assert!(
467            !array
468                .execute_scalar(0, &mut SESSION.create_execution_ctx())
469                .unwrap()
470                .is_null()
471        );
472        assert!(
473            array
474                .execute_scalar(1, &mut SESSION.create_execution_ctx())
475                .unwrap()
476                .is_null()
477        );
478        assert!(
479            !array
480                .execute_scalar(2, &mut SESSION.create_execution_ctx())
481                .unwrap()
482                .is_null()
483        );
484        assert_arrays_eq!(
485            array,
486            PrimitiveArray::from_option_iter([Some(10i32), None, Some(30)]),
487            &mut SESSION.create_execution_ctx()
488        );
489    }
490
491    /// REGRESSION TEST: This test verifies that `append_mask` validates the mask length.
492    ///
493    /// This ensures that masks can only be appended if they match the range length.
494    #[test]
495    #[should_panic(
496        expected = "Tried to append a mask to an `UninitRange` that was beyond the allowed range"
497    )]
498    fn test_append_mask_wrong_length_panics() {
499        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
500            Nullability::Nullable,
501            10,
502            BufferAllocatorRef::static_ref(),
503        );
504        let mut range = builder.uninit_range(5);
505
506        // Try to append a mask with wrong length (3 instead of 5).
507        let wrong_mask = Mask::from_iter([true, false, true]);
508
509        // SAFETY: This is expected to panic due to length mismatch.
510        unsafe {
511            range.append_mask(&wrong_mask);
512        }
513    }
514
515    /// Test that `copy_from_slice` works correctly with different offsets.
516    ///
517    /// This verifies the new simplified API without the redundant `len` parameter.
518    #[test]
519    fn test_copy_from_slice_with_offsets() {
520        let mut ctx = SESSION.create_execution_ctx();
521        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
522            Nullability::NonNullable,
523            10,
524            BufferAllocatorRef::static_ref(),
525        );
526        let mut range = builder.uninit_range(6);
527
528        // Copy to different offsets.
529        range.copy_from_slice(0, &[1, 2]);
530        range.copy_from_slice(2, &[3, 4]);
531        range.copy_from_slice(4, &[5, 6]);
532
533        // SAFETY: We've initialized all 6 values.
534        unsafe {
535            range.finish();
536        }
537
538        let array = builder.finish_into_primitive();
539        assert_arrays_eq!(
540            array,
541            PrimitiveArray::from_iter([1i32, 2, 3, 4, 5, 6]),
542            &mut ctx
543        );
544    }
545
546    /// Test that `set_bit` uses relative indexing within the range.
547    ///
548    /// Note: `set_bit` requires the null buffer to already be initialized, so we first
549    /// use `append_mask` to set up the buffer, then demonstrate that `set_bit` can
550    /// modify individual bits with relative indexing.
551    #[test]
552    fn test_set_bit_relative_indexing() {
553        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
554            Nullability::Nullable,
555            10,
556            BufferAllocatorRef::static_ref(),
557        );
558
559        // First add some values to the builder.
560        builder.append_value(100);
561        builder.append_value(200);
562
563        // Create a range for new values.
564        let mut range = builder.uninit_range(3);
565
566        // Use append_mask to initialize the validity buffer for this range.
567        let initial_mask = Mask::from_iter([false, false, false]);
568        // SAFETY: We're about to initialize the values.
569        unsafe {
570            range.append_mask(&initial_mask);
571        }
572
573        // Now we can use set_bit to modify individual bits with relative indexing.
574        range.set_validity_bit(0, true); // Change first bit to valid
575        range.set_validity_bit(2, true); // Change third bit to valid
576        // Leave middle bit as false (null)
577
578        // Initialize the values.
579        range.copy_from_slice(0, &[10, 20, 30]);
580
581        // SAFETY: We've initialized all 3 values and set their validity.
582        unsafe {
583            range.finish();
584        }
585
586        let array = builder.finish_into_primitive();
587
588        // Verify the total length and values.
589        assert_eq!(array.len(), 5);
590        assert_eq!(array.as_slice::<i32>(), &[100, 200, 10, 20, 30]);
591
592        // Check validity - the first two should be valid (from append_value).
593        assert!(
594            !array
595                .execute_scalar(0, &mut SESSION.create_execution_ctx())
596                .unwrap()
597                .is_null()
598        ); // initial value 100
599        assert!(
600            !array
601                .execute_scalar(1, &mut SESSION.create_execution_ctx())
602                .unwrap()
603                .is_null()
604        ); // initial value 200
605
606        // Check the range items with modified validity.
607        assert!(
608            !array
609                .execute_scalar(2, &mut SESSION.create_execution_ctx())
610                .unwrap()
611                .is_null()
612        ); // range index 0 - set to valid
613        assert!(
614            array
615                .execute_scalar(3, &mut SESSION.create_execution_ctx())
616                .unwrap()
617                .is_null()
618        ); // range index 1 - left as null
619        assert!(
620            !array
621                .execute_scalar(4, &mut SESSION.create_execution_ctx())
622                .unwrap()
623                .is_null()
624        ); // range index 2 - set to valid
625    }
626
627    /// Test that creating a zero-length uninit range panics.
628    #[test]
629    #[should_panic(expected = "cannot create an uninit range of length 0")]
630    fn test_zero_length_uninit_range_panics() {
631        let mut builder = PrimitiveBuilder::<i32>::new_in(
632            Nullability::NonNullable,
633            BufferAllocatorRef::static_ref(),
634        );
635        let _range = builder.uninit_range(0);
636    }
637
638    /// Test that creating an uninit range exceeding capacity panics.
639    #[test]
640    #[should_panic(expected = "uninit_range of len 261 exceeds builder with length 0 and capacity")]
641    fn test_uninit_range_exceeds_capacity_panics() {
642        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
643            Nullability::NonNullable,
644            5,
645            BufferAllocatorRef::static_ref(),
646        );
647        let _range = builder.uninit_range(261);
648    }
649
650    /// Test that `copy_from_slice` debug asserts on out-of-bounds access.
651    ///
652    /// Note: This only panics in debug mode due to `debug_assert!`.
653    #[test]
654    #[cfg(debug_assertions)]
655    #[should_panic(expected = "tried to copy a slice into a `UninitRange` past its boundary")]
656    fn test_copy_from_slice_out_of_bounds() {
657        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
658            Nullability::NonNullable,
659            10,
660            BufferAllocatorRef::static_ref(),
661        );
662        let mut range = builder.uninit_range(3);
663
664        // Try to copy 3 elements starting at offset 1 (would need 4 slots total).
665        range.copy_from_slice(1, &[1, 2, 3]);
666    }
667
668    /// Test that the unsafe contract of `finish` is documented and works correctly.
669    ///
670    /// This test demonstrates proper usage of the unsafe `finish` method.
671    #[test]
672    fn test_finish_unsafe_contract() {
673        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
674            Nullability::Nullable,
675            5,
676            BufferAllocatorRef::static_ref(),
677        );
678        let mut range = builder.uninit_range(3);
679
680        // Set validity mask.
681        let mask = Mask::from_iter([true, true, false]);
682        // SAFETY: We're about to initialize the matching number of values.
683        unsafe {
684            range.append_mask(&mask);
685        }
686
687        // Initialize all values.
688        range.copy_from_slice(0, &[10, 20, 30]);
689
690        // SAFETY: We have initialized all 3 values and set their validity.
691        unsafe {
692            range.finish();
693        }
694
695        let array = builder.finish_into_primitive();
696        assert_eq!(array.len(), 3);
697        assert_eq!(array.as_slice::<i32>(), &[10, 20, 30]);
698        assert_arrays_eq!(
699            array,
700            PrimitiveArray::from_option_iter([Some(10i32), Some(20), None]),
701            &mut SESSION.create_execution_ctx()
702        );
703    }
704
705    #[test]
706    fn test_append_scalar() {
707        use crate::dtype::DType;
708        use crate::scalar::Scalar;
709
710        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
711            Nullability::Nullable,
712            10,
713            BufferAllocatorRef::static_ref(),
714        );
715
716        // Test appending a valid primitive value.
717        let scalar1 = Scalar::primitive(42i32, Nullability::Nullable);
718        builder.append_scalar(&scalar1).unwrap();
719
720        // Test appending another value.
721        let scalar2 = Scalar::primitive(84i32, Nullability::Nullable);
722        builder.append_scalar(&scalar2).unwrap();
723
724        // Test appending null value.
725        let null_scalar = Scalar::null(DType::Primitive(
726            crate::dtype::PType::I32,
727            Nullability::Nullable,
728        ));
729        builder.append_scalar(&null_scalar).unwrap();
730
731        let array = builder.finish_into_primitive();
732        assert_eq!(array.len(), 3);
733
734        // Check actual values.
735        let values = array.as_slice::<i32>();
736        assert_eq!(values[0], 42);
737        assert_eq!(values[1], 84);
738        // values[2] might be any value since it's null.
739
740        // Check validity - first two should be valid, third should be null.
741        let mut ctx = SESSION.create_execution_ctx();
742        assert!(
743            array
744                .validity()
745                .vortex_expect("primitive validity should be derivable")
746                .execute_is_valid(0, &mut ctx)
747                .unwrap()
748        );
749        assert!(
750            array
751                .validity()
752                .vortex_expect("primitive validity should be derivable")
753                .execute_is_valid(1, &mut ctx)
754                .unwrap()
755        );
756        assert!(
757            !array
758                .validity()
759                .vortex_expect("primitive validity should be derivable")
760                .execute_is_valid(2, &mut ctx)
761                .unwrap()
762        );
763
764        // Test wrong dtype error.
765        let mut builder = PrimitiveBuilder::<i32>::with_capacity_in(
766            Nullability::NonNullable,
767            10,
768            BufferAllocatorRef::static_ref(),
769        );
770        let wrong_scalar = Scalar::from(true);
771        assert!(builder.append_scalar(&wrong_scalar).is_err());
772    }
773}