Skip to main content

vortex_array/arrays/constant/vtable/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::fmt::Debug;
5use std::hash::Hash;
6use std::hash::Hasher;
7
8use itertools::Itertools;
9use vortex_error::VortexExpect;
10use vortex_error::VortexResult;
11use vortex_error::vortex_ensure_eq;
12use vortex_error::vortex_panic;
13use vortex_session::VortexSession;
14use vortex_session::registry::CachedId;
15
16use crate::ArrayEq;
17use crate::ArrayHash;
18use crate::ArrayParts;
19use crate::ArrayRef;
20use crate::ArraySlots;
21use crate::EqMode;
22use crate::ExecutionCtx;
23use crate::ExecutionResult;
24use crate::IntoArray;
25use crate::array::Array;
26use crate::array::ArrayId;
27use crate::array::ArrayView;
28use crate::array::VTable;
29use crate::array::unsupported_buffer_replacement;
30use crate::arrays::ExtensionArray;
31use crate::arrays::constant::ConstantData;
32use crate::arrays::constant::compute::rules::PARENT_RULES;
33use crate::arrays::constant::vtable::canonical::constant_canonicalize;
34use crate::buffer::BufferHandle;
35use crate::builders::ArrayBuilder;
36use crate::builders::BoolBuilder;
37use crate::builders::DecimalBuilder;
38use crate::builders::FixedSizeListBuilder;
39use crate::builders::ListViewBuilder;
40use crate::builders::NullBuilder;
41use crate::builders::PrimitiveBuilder;
42use crate::builders::VarBinViewBuilder;
43use crate::builders::builder_with_capacity_in;
44use crate::canonical::Canonical;
45use crate::dtype::DType;
46use crate::dtype::OffsetBuilderPType;
47use crate::match_each_decimal_value;
48use crate::match_each_listview_builder;
49use crate::match_each_native_ptype;
50use crate::match_each_varbin_builder;
51use crate::scalar::DecimalValue;
52use crate::scalar::ListScalar;
53use crate::scalar::Scalar;
54use crate::scalar::ScalarValue;
55use crate::serde::ArrayChildren;
56pub(crate) mod canonical;
57mod operations;
58mod validity;
59
60/// A [`Constant`]-encoded Vortex array.
61pub type ConstantArray = Array<Constant>;
62
63#[derive(Clone, Debug)]
64pub struct Constant;
65
66impl ArrayHash for ConstantData {
67    fn array_hash<H: Hasher>(&self, state: &mut H, _accuracy: EqMode) {
68        self.scalar.hash(state);
69    }
70}
71
72impl ArrayEq for ConstantData {
73    fn array_eq(&self, other: &Self, _accuracy: EqMode) -> bool {
74        self.scalar == other.scalar
75    }
76}
77
78impl VTable for Constant {
79    type TypedArrayData = ConstantData;
80
81    type OperationsVTable = Self;
82    type ValidityVTable = Self;
83
84    fn id(&self) -> ArrayId {
85        static ID: CachedId = CachedId::new("vortex.constant");
86        *ID
87    }
88
89    fn validate(
90        &self,
91        data: &ConstantData,
92        dtype: &DType,
93        _len: usize,
94        _slots: &[Option<ArrayRef>],
95    ) -> VortexResult<()> {
96        vortex_ensure_eq!(
97            data.scalar.dtype(),
98            dtype,
99            "ConstantArray scalar dtype does not match outer dtype",
100        );
101        Ok(())
102    }
103
104    fn nbuffers(_array: ArrayView<'_, Self>) -> usize {
105        1
106    }
107
108    fn buffer(array: ArrayView<'_, Self>, idx: usize) -> BufferHandle {
109        match idx {
110            0 => BufferHandle::new_host(
111                ScalarValue::to_proto_bytes::<Vec<u8>>(array.scalar.value()).into(),
112            ),
113            _ => vortex_panic!("ConstantArray buffer index {idx} out of bounds"),
114        }
115    }
116
117    fn buffer_name(_array: ArrayView<'_, Self>, idx: usize) -> Option<String> {
118        match idx {
119            0 => Some("scalar".to_string()),
120            _ => None,
121        }
122    }
123
124    fn with_buffers(
125        &self,
126        array: ArrayView<'_, Self>,
127        buffers: &[BufferHandle],
128    ) -> VortexResult<ArrayParts<Self>> {
129        unsupported_buffer_replacement(array, buffers)
130    }
131
132    fn slot_name(_array: ArrayView<'_, Self>, idx: usize) -> String {
133        vortex_panic!("ConstantArray slot_name index {idx} out of bounds")
134    }
135
136    fn serialize(
137        _array: ArrayView<'_, Self>,
138        _session: &VortexSession,
139    ) -> VortexResult<Option<Vec<u8>>> {
140        // HACK: Because the scalar is stored in the buffers, we do not need to serialize the
141        // metadata at all.
142        Ok(Some(vec![]))
143    }
144
145    fn deserialize(
146        &self,
147        dtype: &DType,
148        len: usize,
149        _metadata: &[u8],
150
151        buffers: &[BufferHandle],
152        _children: &dyn ArrayChildren,
153        session: &VortexSession,
154    ) -> VortexResult<ArrayParts<Self>> {
155        vortex_ensure_eq!(buffers.len(), 1);
156
157        let buffer = buffers[0].clone().try_to_host_sync()?;
158        let bytes: &[u8] = buffer.as_ref();
159
160        let scalar_value = ScalarValue::from_proto_bytes(bytes, dtype, session)?;
161        let scalar = Scalar::try_new(dtype.clone(), scalar_value)?;
162
163        Ok(ArrayParts::new(
164            self.clone(),
165            dtype.clone(),
166            len,
167            ConstantData::new(scalar),
168            ArraySlots::new(),
169        ))
170    }
171
172    fn reduce_parent(
173        array: ArrayView<'_, Self>,
174        parent: &ArrayRef,
175        child_idx: usize,
176    ) -> VortexResult<Option<ArrayRef>> {
177        PARENT_RULES.evaluate(array, parent, child_idx)
178    }
179
180    fn execute(array: Array<Self>, ctx: &mut ExecutionCtx) -> VortexResult<ExecutionResult> {
181        Ok(ExecutionResult::done(constant_canonicalize(
182            array.as_view(),
183            ctx,
184        )?))
185    }
186
187    fn append_to_builder(
188        array: ArrayView<'_, Self>,
189        builder: &mut dyn ArrayBuilder,
190        ctx: &mut ExecutionCtx,
191    ) -> VortexResult<()> {
192        let n = array.len();
193        let scalar = array.scalar();
194
195        match array.dtype() {
196            DType::Null => append_value_or_nulls::<NullBuilder>(builder, true, n, |_| {}),
197            DType::Bool(_) => {
198                append_value_or_nulls::<BoolBuilder>(builder, scalar.is_null(), n, |b| {
199                    b.append_values(
200                        scalar
201                            .as_bool()
202                            .value()
203                            .vortex_expect("non-null bool scalar must have a value"),
204                        n,
205                    );
206                })
207            }
208            DType::Primitive(ptype, _) => {
209                match_each_native_ptype!(ptype, |P| {
210                    append_value_or_nulls::<PrimitiveBuilder<P>>(
211                        builder,
212                        scalar.is_null(),
213                        n,
214                        |b| {
215                            let value = P::try_from(scalar)
216                                .vortex_expect("Couldn't unwrap constant scalar to primitive");
217                            b.append_n_values(value, n);
218                        },
219                    );
220                });
221            }
222            DType::Decimal(..) => {
223                append_value_or_nulls::<DecimalBuilder>(builder, scalar.is_null(), n, |b| {
224                    let value = scalar
225                        .as_decimal()
226                        .decimal_value()
227                        .vortex_expect("non-null decimal scalar must have a value");
228                    match_each_decimal_value!(value, |v| { b.append_n_values(v, n) });
229                });
230            }
231            DType::Utf8(_) => {
232                if let Some(result) = match_each_varbin_builder!(builder, |builder| {
233                    builder.append_scalar_repeated(scalar, n)
234                }) {
235                    result?;
236                } else {
237                    append_value_or_nulls::<VarBinViewBuilder>(builder, scalar.is_null(), n, |b| {
238                        let value = scalar
239                            .as_utf8()
240                            .value()
241                            .vortex_expect("non-null utf8 scalar must have a value");
242                        b.append_n_values(value.as_bytes(), n);
243                    });
244                }
245            }
246            DType::Binary(_) => {
247                if let Some(result) = match_each_varbin_builder!(builder, |builder| {
248                    builder.append_scalar_repeated(scalar, n)
249                }) {
250                    result?;
251                } else {
252                    append_value_or_nulls::<VarBinViewBuilder>(builder, scalar.is_null(), n, |b| {
253                        let value = scalar
254                            .as_binary()
255                            .value()
256                            .vortex_expect("non-null binary scalar must have a value");
257                        b.append_n_values(value, n);
258                    });
259                }
260            }
261            DType::List(..) => append_constant_list_run(array, n, builder, ctx)?,
262            DType::Extension(ext_dtype) => {
263                // An extension array is its storage wearing a dtype, so a run of identical values
264                // is a constant storage array, which stays constant-encoded in the builder.
265                // Canonicalizing instead would materialize the storage: see the note in
266                // `constant_canonicalize` about `ExtensionConstantRule`.
267                let storage = ConstantArray::new(scalar.as_extension().to_storage_scalar(), n);
268                ExtensionArray::new(ext_dtype.clone(), storage.into_array())
269                    .into_array()
270                    .append_to_builder(builder, ctx)?
271            }
272            DType::FixedSizeList(..) => {
273                append_constant_fixed_size_list_run(array, n, builder, ctx)?
274            }
275            // The remaining dtypes canonicalize cheaply: a constant struct canonicalizes to
276            // constant fields, and a constant map to views sharing one copy of the entries, so
277            // appending the canonical array preserves the run's economy.
278            // TODO: add a fast path for DType::Union once it has a builder.
279            _ => append_via_canonical(array, builder, ctx)?,
280        }
281
282        Ok(())
283    }
284}
285
286/// Appends the constant list `array` as one run sharing a single copy of its elements.
287///
288/// The list's elements materialize once, and
289/// [`ListViewBuilder::append_array_as_repeated_list`] points the run's `n` views at that one
290/// copy. Only a list-view builder has a layout that can share elements; any other builder for a
291/// list dtype - a [`ListBuilder`](crate::builders::ListBuilder), whose offsets can only describe
292/// contiguous lists - appends the canonical run instead.
293fn append_constant_list_run(
294    array: ArrayView<'_, Constant>,
295    n: usize,
296    builder: &mut dyn ArrayBuilder,
297    ctx: &mut ExecutionCtx,
298) -> VortexResult<()> {
299    let scalar = array.scalar();
300    match match_each_listview_builder!(builder, |b| append_repeated_list_run(
301        b,
302        scalar.as_list(),
303        n,
304        ctx
305    )) {
306        Some(result) => result,
307        None => append_via_canonical(array, builder, ctx),
308    }
309}
310
311/// Appends the list `scalar` to a [`ListViewBuilder`] `n` times, storing its elements once.
312fn append_repeated_list_run<O: OffsetBuilderPType, S: OffsetBuilderPType>(
313    builder: &mut ListViewBuilder<O, S>,
314    scalar: ListScalar,
315    n: usize,
316    ctx: &mut ExecutionCtx,
317) -> VortexResult<()> {
318    if n == 0 {
319        return Ok(());
320    }
321
322    let Some(elements) = scalar.elements() else {
323        // A null run stores no elements at all.
324        builder.append_nulls(n);
325        return Ok(());
326    };
327
328    let mut elements_builder =
329        builder_with_capacity_in(scalar.element_dtype(), elements.len(), ctx.allocator());
330    for element in &elements {
331        elements_builder.append_scalar(element)?;
332    }
333
334    builder.append_array_as_repeated_list(&elements_builder.finish(), n, ctx)
335}
336
337/// Appends the constant fixed-size-list `array` as its list's elements tiled `n` times.
338///
339/// The list's elements materialize into a tile once - a single [`ConstantArray`] when they are
340/// all the same scalar, so that the tiling costs nothing - and
341/// [`FixedSizeListBuilder::append_array_as_repeated_list`] shares that one tile across the run.
342fn append_constant_fixed_size_list_run(
343    array: ArrayView<'_, Constant>,
344    n: usize,
345    builder: &mut dyn ArrayBuilder,
346    ctx: &mut ExecutionCtx,
347) -> VortexResult<()> {
348    let Some(builder) = builder.as_any_mut().downcast_mut::<FixedSizeListBuilder>() else {
349        return append_via_canonical(array, builder, ctx);
350    };
351
352    if n == 0 {
353        return Ok(());
354    }
355
356    let scalar = array.scalar().as_list();
357    let Some(elements) = scalar.elements() else {
358        // A null run stores no elements of its own, only the placeholders the builder writes.
359        builder.append_nulls(n);
360        return Ok(());
361    };
362
363    let tile = match elements.iter().all_equal_value() {
364        Ok(uniform) => ConstantArray::new(uniform.clone(), elements.len()).into_array(),
365        Err(_) => {
366            let mut tile_builder =
367                builder_with_capacity_in(builder.element_dtype(), elements.len(), ctx.allocator());
368            for element in &elements {
369                tile_builder.append_scalar(element)?;
370            }
371            tile_builder.finish()
372        }
373    };
374
375    builder.append_array_as_repeated_list(&tile, n, ctx)
376}
377
378/// Appends `array` by canonicalizing it first, for the dtypes with no fast path of their own.
379fn append_via_canonical(
380    array: ArrayView<'_, Constant>,
381    builder: &mut dyn ArrayBuilder,
382    ctx: &mut ExecutionCtx,
383) -> VortexResult<()> {
384    let canonical = array
385        .array()
386        .clone()
387        .execute::<Canonical>(ctx)?
388        .into_array();
389    canonical.append_to_builder(builder, ctx)
390}
391
392/// Downcasts `builder` to `B`, then either appends `n` nulls or calls `fill` with the typed
393/// builder depending on `is_null`.
394///
395/// `is_null` must only be `true` when the builder is nullable.
396fn append_value_or_nulls<B: ArrayBuilder + 'static>(
397    builder: &mut dyn ArrayBuilder,
398    is_null: bool,
399    n: usize,
400    fill: impl FnOnce(&mut B),
401) {
402    let b = builder
403        .as_any_mut()
404        .downcast_mut::<B>()
405        .vortex_expect("builder dtype must match array dtype");
406    if is_null {
407        // SAFETY: is_null=true only when the scalar (and thus the builder) is nullable.
408        unsafe { b.append_nulls_unchecked(n) };
409    } else {
410        fill(b);
411    }
412}
413
414#[cfg(test)]
415mod tests {
416    use std::sync::Arc;
417    use std::sync::LazyLock;
418
419    use rstest::rstest;
420    use vortex_error::VortexResult;
421    use vortex_session::VortexSession;
422
423    use crate::ArrayRef;
424    use crate::ExecutionCtx;
425    use crate::IntoArray;
426    use crate::VortexSessionExecute;
427    use crate::arrays::Chunked;
428    use crate::arrays::Constant;
429    use crate::arrays::ConstantArray;
430    use crate::arrays::Extension;
431    use crate::arrays::FixedSizeList;
432    use crate::arrays::ListView;
433    use crate::arrays::Struct;
434    use crate::arrays::chunked::ChunkedArrayExt;
435    use crate::arrays::constant::vtable::canonical::constant_canonicalize;
436    use crate::arrays::extension::ExtensionArrayExt;
437    use crate::arrays::fixed_size_list::FixedSizeListArraySlotsExt;
438    use crate::arrays::listview::ListViewArraySlotsExt;
439    use crate::arrays::struct_::StructArrayExt;
440    use crate::assert_arrays_eq;
441    use crate::builders::ArrayBuilder;
442    use crate::builders::ListBuilder;
443    use crate::builders::builder_with_capacity_in;
444    use crate::dtype::DType;
445    use crate::dtype::Nullability;
446    use crate::dtype::PType;
447    use crate::dtype::StructFields;
448    use crate::extension::datetime::Date;
449    use crate::extension::datetime::TimeUnit;
450    use crate::scalar::Scalar;
451
452    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
453
454    fn assert_constant_values(
455        array: &ArrayRef,
456        scalar: &Scalar,
457        len: usize,
458        ctx: &mut ExecutionCtx,
459    ) -> VortexResult<()> {
460        assert_eq!(array.dtype(), scalar.dtype());
461        assert_eq!(array.len(), len);
462        for index in 0..len {
463            assert_eq!(&array.execute_scalar(index, ctx)?, scalar);
464        }
465        Ok(())
466    }
467
468    /// Checks append against both the fixture scalar and the canonicalization path.
469    fn assert_append_matches_canonical(array: ConstantArray) -> VortexResult<()> {
470        let mut ctx = SESSION.create_execution_ctx();
471
472        let scalar = array.scalar().clone();
473        let len = array.len();
474        let expected = constant_canonicalize(array.as_view(), &mut ctx)?.into_array();
475        let mut builder = builder_with_capacity_in(
476            array.dtype(),
477            array.len(),
478            vortex_buffer::BufferAllocatorRef::static_ref(),
479        );
480        array
481            .into_array()
482            .append_to_builder(builder.as_mut(), &mut ctx)?;
483        let result = builder.finish();
484        assert_arrays_eq!(&result, &expected, &mut ctx);
485        assert_constant_values(&result, &scalar, len, &mut ctx)?;
486        Ok(())
487    }
488
489    #[test]
490    fn test_null_constant_append() -> VortexResult<()> {
491        assert_append_matches_canonical(ConstantArray::new(Scalar::null(DType::Null), 5))
492    }
493
494    #[test]
495    fn test_with_buffers_rejects_serialized_scalar_buffer() {
496        let array =
497            ConstantArray::new(Scalar::primitive(42i32, Nullability::NonNullable), 3).into_array();
498        let buffers = array.buffer_handles();
499
500        // SAFETY: the replacement buffers are the array's existing buffers, so the logical values
501        // would be unchanged if the encoding supported buffer replacement.
502        let Err(err) = (unsafe { array.with_buffers(buffers) }) else {
503            panic!("ConstantArray should reject replacing its serialized scalar buffer");
504        };
505        assert!(
506            err.to_string()
507                .contains("does not support in-memory buffer replacement")
508        );
509    }
510
511    #[rstest]
512    #[case::bool_true(true, 5)]
513    #[case::bool_false(false, 3)]
514    fn test_bool_constant_append(#[case] value: bool, #[case] n: usize) -> VortexResult<()> {
515        assert_append_matches_canonical(ConstantArray::new(
516            Scalar::bool(value, Nullability::NonNullable),
517            n,
518        ))
519    }
520
521    #[test]
522    fn test_bool_null_constant_append() -> VortexResult<()> {
523        assert_append_matches_canonical(ConstantArray::new(
524            Scalar::null(DType::Bool(Nullability::Nullable)),
525            4,
526        ))
527    }
528
529    #[rstest]
530    #[case::i32(Scalar::primitive(42i32, Nullability::NonNullable), 5)]
531    #[case::u8(Scalar::primitive(7u8, Nullability::NonNullable), 3)]
532    #[case::f64(Scalar::primitive(1.5f64, Nullability::NonNullable), 4)]
533    #[case::i32_null(Scalar::null(DType::Primitive(PType::I32, Nullability::Nullable)), 3)]
534    fn test_primitive_constant_append(
535        #[case] scalar: Scalar,
536        #[case] n: usize,
537    ) -> VortexResult<()> {
538        assert_append_matches_canonical(ConstantArray::new(scalar, n))
539    }
540
541    #[rstest]
542    #[case::utf8_inline("hi", 5)] // ≤12 bytes: inlined in BinaryView
543    #[case::utf8_noninline("hello world!!", 5)] // >12 bytes: requires buffer block
544    #[case::utf8_empty("", 3)]
545    #[case::utf8_n_zero("hello world!!", 0)] // n=0 with non-inline: must not write orphaned bytes
546    fn test_utf8_constant_append(#[case] value: &str, #[case] n: usize) -> VortexResult<()> {
547        assert_append_matches_canonical(ConstantArray::new(
548            Scalar::utf8(value, Nullability::NonNullable),
549            n,
550        ))
551    }
552
553    #[test]
554    fn test_utf8_null_constant_append() -> VortexResult<()> {
555        assert_append_matches_canonical(ConstantArray::new(
556            Scalar::null(DType::Utf8(Nullability::Nullable)),
557            4,
558        ))
559    }
560
561    #[rstest]
562    #[case::binary_inline(vec![1u8, 2, 3], 5)] // ≤12 bytes: inlined
563    #[case::binary_noninline(vec![0u8; 13], 5)] // >12 bytes: buffer block
564    fn test_binary_constant_append(#[case] value: Vec<u8>, #[case] n: usize) -> VortexResult<()> {
565        assert_append_matches_canonical(ConstantArray::new(
566            Scalar::binary(value, Nullability::NonNullable),
567            n,
568        ))
569    }
570
571    #[test]
572    fn test_binary_null_constant_append() -> VortexResult<()> {
573        assert_append_matches_canonical(ConstantArray::new(
574            Scalar::null(DType::Binary(Nullability::Nullable)),
575            4,
576        ))
577    }
578
579    #[rstest]
580    #[case::non_empty(vec![Scalar::from(1i32), Scalar::from(2i32)], 4)]
581    #[case::empty(vec![], 3)]
582    #[case::n_zero(vec![Scalar::from(1i32)], 0)]
583    fn test_list_constant_append(
584        #[case] elements: Vec<Scalar>,
585        #[case] n: usize,
586    ) -> VortexResult<()> {
587        let scalar = Scalar::list(
588            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable)),
589            elements,
590            Nullability::NonNullable,
591        );
592        assert_append_matches_canonical(ConstantArray::new(scalar, n))
593    }
594
595    #[test]
596    fn test_null_list_constant_append() -> VortexResult<()> {
597        let dtype = DType::List(
598            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable)),
599            Nullability::Nullable,
600        );
601        assert_append_matches_canonical(ConstantArray::new(Scalar::null(dtype), 3))
602    }
603
604    /// A run of identical lists appended into a list-view builder shares one copy of its elements
605    /// across the whole run.
606    #[test]
607    fn test_list_constant_append_keeps_one_copy_of_the_elements() -> VortexResult<()> {
608        let mut ctx = SESSION.create_execution_ctx();
609        let scalar = Scalar::list(
610            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable)),
611            vec![Scalar::from(1i32), Scalar::from(2i32), Scalar::from(3i32)],
612            Nullability::NonNullable,
613        );
614        let array = ConstantArray::new(scalar.clone(), 1_000);
615
616        let mut builder = builder_with_capacity_in(
617            array.dtype(),
618            array.len(),
619            vortex_buffer::BufferAllocatorRef::static_ref(),
620        );
621        array
622            .into_array()
623            .append_to_builder(builder.as_mut(), &mut ctx)?;
624        let result = builder.finish();
625        assert_constant_values(&result, &scalar, 1_000, &mut ctx)?;
626
627        assert_eq!(
628            result.as_::<ListView>().elements().len(),
629            3,
630            "the run's elements should be stored once, not once per row",
631        );
632        Ok(())
633    }
634
635    /// A `ListBuilder`'s offsets can only describe contiguous lists, so a constant run cannot
636    /// share its elements there and takes the canonical path instead.
637    #[test]
638    fn test_list_constant_append_into_list_builder() -> VortexResult<()> {
639        let mut ctx = SESSION.create_execution_ctx();
640        let element_dtype: Arc<DType> =
641            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable));
642        let scalar = Scalar::list(
643            Arc::clone(&element_dtype),
644            vec![Scalar::from(1i32), Scalar::from(2i32)],
645            Nullability::NonNullable,
646        );
647        let array = ConstantArray::new(scalar, 4).into_array();
648
649        let mut builder = ListBuilder::<u32>::with_capacity_in(
650            element_dtype,
651            Nullability::NonNullable,
652            0,
653            0,
654            vortex_buffer::BufferAllocatorRef::static_ref(),
655        );
656        array.append_to_builder(&mut builder, &mut ctx)?;
657
658        assert_arrays_eq!(&builder.finish(), &array, &mut ctx);
659        Ok(())
660    }
661
662    #[test]
663    fn test_struct_constant_append() -> VortexResult<()> {
664        let fields = StructFields::new(
665            ["x", "y"].into(),
666            vec![
667                DType::Primitive(PType::I32, Nullability::NonNullable),
668                DType::Utf8(Nullability::NonNullable),
669            ],
670        );
671        let scalar = Scalar::struct_(
672            DType::Struct(fields, Nullability::NonNullable),
673            [
674                Scalar::primitive(42i32, Nullability::NonNullable),
675                Scalar::utf8("hi", Nullability::NonNullable),
676            ],
677        );
678        assert_append_matches_canonical(ConstantArray::new(scalar, 3))
679    }
680
681    #[test]
682    fn test_null_struct_constant_append() -> VortexResult<()> {
683        let fields = StructFields::new(
684            ["x"].into(),
685            vec![DType::Primitive(PType::I32, Nullability::Nullable)],
686        );
687        let dtype = DType::Struct(fields, Nullability::Nullable);
688        assert_append_matches_canonical(ConstantArray::new(Scalar::null(dtype), 4))
689    }
690
691    /// A run of identical structs should leave each field constant-encoded rather than materialize
692    /// a value per row per field.
693    #[test]
694    fn test_struct_constant_append_keeps_fields_constant() -> VortexResult<()> {
695        let mut ctx = SESSION.create_execution_ctx();
696        let fields = StructFields::new(
697            ["x", "y"].into(),
698            vec![
699                DType::Primitive(PType::I32, Nullability::NonNullable),
700                DType::Utf8(Nullability::NonNullable),
701            ],
702        );
703        let scalar = Scalar::struct_(
704            DType::Struct(fields, Nullability::NonNullable),
705            [
706                Scalar::primitive(42i32, Nullability::NonNullable),
707                Scalar::utf8("hi", Nullability::NonNullable),
708            ],
709        );
710        let array = ConstantArray::new(scalar.clone(), 1_000);
711
712        let mut builder = builder_with_capacity_in(
713            array.dtype(),
714            array.len(),
715            vortex_buffer::BufferAllocatorRef::static_ref(),
716        );
717        array
718            .into_array()
719            .append_to_builder(builder.as_mut(), &mut ctx)?;
720        let result = builder.finish();
721        assert_constant_values(&result, &scalar, 1_000, &mut ctx)?;
722
723        let struct_array = result.as_::<Struct>();
724        for field in 0..2 {
725            assert!(
726                struct_array.unmasked_field(field).is::<Constant>(),
727                "field {field} should have stayed constant-encoded",
728            );
729        }
730        Ok(())
731    }
732
733    #[rstest]
734    #[case::non_uniform(vec![Scalar::from(1i32), Scalar::from(2i32)])]
735    #[case::uniform(vec![Scalar::from(7i32), Scalar::from(7i32)])]
736    fn test_fixed_size_list_constant_append(#[case] elements: Vec<Scalar>) -> VortexResult<()> {
737        let scalar = Scalar::fixed_size_list(
738            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable)),
739            elements,
740            Nullability::NonNullable,
741        );
742        assert_append_matches_canonical(ConstantArray::new(scalar, 4))
743    }
744
745    #[test]
746    fn test_null_fixed_size_list_constant_append() -> VortexResult<()> {
747        let dtype = DType::FixedSizeList(
748            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable)),
749            2,
750            Nullability::Nullable,
751        );
752        assert_append_matches_canonical(ConstantArray::new(Scalar::null(dtype), 3))
753    }
754
755    /// A fixed-size list whose elements are all the same scalar tiles a constant array, so the
756    /// tile's chunks stay constant-encoded rather than materializing a value per row.
757    #[test]
758    fn test_uniform_fixed_size_list_constant_append_keeps_elements_constant() -> VortexResult<()> {
759        let mut ctx = SESSION.create_execution_ctx();
760        let scalar = Scalar::fixed_size_list(
761            Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable)),
762            vec![Scalar::from(7i32), Scalar::from(7i32)],
763            Nullability::NonNullable,
764        );
765        let array = ConstantArray::new(scalar.clone(), 1_000);
766
767        let mut builder = builder_with_capacity_in(
768            array.dtype(),
769            array.len(),
770            vortex_buffer::BufferAllocatorRef::static_ref(),
771        );
772        array
773            .into_array()
774            .append_to_builder(builder.as_mut(), &mut ctx)?;
775        let result = builder.finish();
776        assert_constant_values(&result, &scalar, 1_000, &mut ctx)?;
777
778        let elements = result.as_::<FixedSizeList>().elements().clone();
779        assert!(
780            elements
781                .as_::<Chunked>()
782                .iter_chunks()
783                .all(|chunk| chunk.is::<Constant>()),
784            "a uniform tile should have stayed constant-encoded",
785        );
786        Ok(())
787    }
788
789    #[test]
790    fn test_extension_constant_append() -> VortexResult<()> {
791        let scalar = Scalar::extension::<Date>(TimeUnit::Days, Scalar::from(Some(42i32)));
792        assert_append_matches_canonical(ConstantArray::new(scalar, 5))
793    }
794
795    /// An extension array is its storage wearing a dtype, so a run of identical values should leave
796    /// the storage constant-encoded.
797    #[test]
798    fn test_extension_constant_append_keeps_storage_constant() -> VortexResult<()> {
799        let mut ctx = SESSION.create_execution_ctx();
800        let scalar = Scalar::extension::<Date>(TimeUnit::Days, Scalar::from(Some(42i32)));
801        let array = ConstantArray::new(scalar.clone(), 1_000);
802
803        let mut builder = builder_with_capacity_in(
804            array.dtype(),
805            array.len(),
806            vortex_buffer::BufferAllocatorRef::static_ref(),
807        );
808        array
809            .into_array()
810            .append_to_builder(builder.as_mut(), &mut ctx)?;
811        let result = builder.finish();
812        assert_constant_values(&result, &scalar, 1_000, &mut ctx)?;
813
814        assert!(
815            result.as_::<Extension>().storage_array().is::<Constant>(),
816            "the storage should have stayed constant-encoded",
817        );
818        Ok(())
819    }
820}