1use 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
27pub struct PrimitiveBuilder<T> {
29 dtype: DType,
30 values: BufferMut<T>,
31 nulls: LazyBitBufferBuilder,
32}
33
34impl<T: NativePType> PrimitiveBuilder<T> {
35 #[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 pub fn new_in(nullability: Nullability, allocator: &BufferAllocatorRef) -> Self {
43 Self::with_capacity_in(nullability, DEFAULT_BUILDER_CAPACITY, allocator)
44 }
45
46 #[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 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 pub fn append_value(&mut self, value: T) {
67 self.values.push(value);
68 self.nulls.append_non_null();
69 }
70
71 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 pub fn values(&self) -> &[T] {
79 self.values.as_ref()
80 }
81
82 pub fn values_mut(&mut self) -> &mut [T] {
84 self.values.as_mut()
85 }
86
87 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 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 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
231pub struct UninitRange<'a, T> {
233 len: usize,
237
238 builder: &'a mut PrimitiveBuilder<T>,
243}
244
245impl<T> UninitRange<'_, T> {
246 #[inline]
248 pub fn len(&self) -> usize {
249 self.len
250 }
251
252 #[inline]
254 pub fn is_empty(&self) -> bool {
255 self.len == 0
256 }
257
258 #[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 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 self.builder.nulls.append_validity_mask(mask);
293 }
294
295 pub fn set_validity_bit(&mut self, index: usize, v: bool) {
302 assert!(index < self.len, "set_bit index out of bounds");
303 let absolute_index = self.builder.values.len() + index;
306 self.builder.nulls.set_bit(absolute_index, v);
307 }
308
309 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 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 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 pub unsafe fn finish(self) {
367 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 #[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 let mut range1 = builder.uninit_range(3);
401 range1.copy_from_slice(0, &[1, 2, 3]);
402
403 unsafe {
405 range1.finish();
406 }
407
408 assert_eq!(builder.values(), &[1, 2, 3]);
410
411 let mut range2 = builder.uninit_range(2);
413
414 range2.copy_from_slice(0, &[4, 5]);
416
417 unsafe {
419 range2.finish();
420 }
421
422 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 #[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 let mask = Mask::from_iter([true, false, true]);
449
450 unsafe {
452 range.append_mask(&mask);
453 }
454
455 range.copy_from_slice(0, &[10, 20, 30]);
457
458 unsafe {
460 range.finish();
461 }
462
463 let array = builder.finish_into_primitive();
464 assert_eq!(array.len(), 3);
465 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 #[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 let wrong_mask = Mask::from_iter([true, false, true]);
508
509 unsafe {
511 range.append_mask(&wrong_mask);
512 }
513 }
514
515 #[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 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 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]
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 builder.append_value(100);
561 builder.append_value(200);
562
563 let mut range = builder.uninit_range(3);
565
566 let initial_mask = Mask::from_iter([false, false, false]);
568 unsafe {
570 range.append_mask(&initial_mask);
571 }
572
573 range.set_validity_bit(0, true); range.set_validity_bit(2, true); range.copy_from_slice(0, &[10, 20, 30]);
580
581 unsafe {
583 range.finish();
584 }
585
586 let array = builder.finish_into_primitive();
587
588 assert_eq!(array.len(), 5);
590 assert_eq!(array.as_slice::<i32>(), &[100, 200, 10, 20, 30]);
591
592 assert!(
594 !array
595 .execute_scalar(0, &mut SESSION.create_execution_ctx())
596 .unwrap()
597 .is_null()
598 ); assert!(
600 !array
601 .execute_scalar(1, &mut SESSION.create_execution_ctx())
602 .unwrap()
603 .is_null()
604 ); assert!(
608 !array
609 .execute_scalar(2, &mut SESSION.create_execution_ctx())
610 .unwrap()
611 .is_null()
612 ); assert!(
614 array
615 .execute_scalar(3, &mut SESSION.create_execution_ctx())
616 .unwrap()
617 .is_null()
618 ); assert!(
620 !array
621 .execute_scalar(4, &mut SESSION.create_execution_ctx())
622 .unwrap()
623 .is_null()
624 ); }
626
627 #[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]
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]
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 range.copy_from_slice(1, &[1, 2, 3]);
666 }
667
668 #[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 let mask = Mask::from_iter([true, true, false]);
682 unsafe {
684 range.append_mask(&mask);
685 }
686
687 range.copy_from_slice(0, &[10, 20, 30]);
689
690 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 let scalar1 = Scalar::primitive(42i32, Nullability::Nullable);
718 builder.append_scalar(&scalar1).unwrap();
719
720 let scalar2 = Scalar::primitive(84i32, Nullability::Nullable);
722 builder.append_scalar(&scalar2).unwrap();
723
724 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 let values = array.as_slice::<i32>();
736 assert_eq!(values[0], 42);
737 assert_eq!(values[1], 84);
738 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 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}