Skip to main content

vortex_array/scalar/
scalar_impl.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Core [`Scalar`] type definition.
5
6use std::cmp::Ordering;
7use std::hash::Hash;
8use std::hash::Hasher;
9
10use vortex_error::VortexResult;
11use vortex_error::vortex_ensure_eq;
12use vortex_error::vortex_err;
13use vortex_error::vortex_panic;
14
15use crate::dtype::DType;
16use crate::dtype::NativeDType;
17use crate::dtype::PType;
18use crate::dtype::StructFields;
19use crate::dtype::half::f16;
20use crate::scalar::PValue;
21use crate::scalar::Scalar;
22use crate::scalar::ScalarValue;
23
24impl Scalar {
25    // Constructors for null scalars.
26
27    /// Creates a new null [`Scalar`] with the given [`DType`].
28    ///
29    /// # Panics
30    ///
31    /// Panics if the given [`DType`] is non-nullable.
32    pub fn null(dtype: DType) -> Self {
33        assert!(
34            dtype.is_nullable(),
35            "Cannot create null scalar with non-nullable dtype {dtype}"
36        );
37
38        Self { dtype, value: None }
39    }
40
41    // TODO(connor): This method arguably shouldn't exist...
42    /// Creates a new null [`Scalar`] for the given scalar type.
43    ///
44    /// The resulting scalar will have a nullable version of the type's data type.
45    pub fn null_native<T: NativeDType>() -> Self {
46        Self {
47            dtype: T::dtype().as_nullable(),
48            value: None,
49        }
50    }
51
52    // Constructors for potentially null scalars.
53
54    /// Creates a new [`Scalar`] with the given [`DType`] and potentially null [`ScalarValue`].
55    ///
56    /// This is just a helper function for tests.
57    ///
58    /// # Panics
59    ///
60    /// Panics if the given [`DType`] and [`ScalarValue`] are incompatible.
61    #[cfg(test)]
62    pub fn new(dtype: DType, value: Option<ScalarValue>) -> Self {
63        use vortex_error::VortexExpect;
64
65        Self::try_new(dtype, value).vortex_expect("Failed to create Scalar")
66    }
67
68    /// Attempts to create a new [`Scalar`] with the given [`DType`] and potentially null
69    /// [`ScalarValue`].
70    ///
71    /// Legacy `U64` bit representations of `F16` are converted to `F16` during construction.
72    /// Nested and extension values must already match their storage dtypes.
73    ///
74    /// # Errors
75    ///
76    /// Returns an error if the given [`DType`] and [`ScalarValue`] are incompatible.
77    #[inline]
78    pub fn try_new(dtype: DType, value: Option<ScalarValue>) -> VortexResult<Self> {
79        if Self::is_compatible(&dtype, value.as_ref()) {
80            return Ok(Self { dtype, value });
81        }
82
83        Self::try_new_fallback(dtype, value)
84    }
85
86    /// Converts legacy `F16` values or reports why the value is incompatible.
87    ///
88    /// It owns the parts so their drop code stays out of the canonical construction path.
89    #[cold]
90    #[inline(never)]
91    fn try_new_fallback(dtype: DType, value: Option<ScalarValue>) -> VortexResult<Self> {
92        let value = match (&dtype, value) {
93            (DType::Primitive(PType::F16, _), Some(ScalarValue::Primitive(PValue::U64(bits)))) => {
94                let bits = u16::try_from(bits).map_err(|_| {
95                    vortex_err!("f16 bit representation must fit in 16 bits, got {bits}")
96                })?;
97
98                Some(ScalarValue::Primitive(PValue::F16(f16::from_bits(bits))))
99            }
100            (_, value) => return Err(Self::incompatible_error(&dtype, value.as_ref())),
101        };
102
103        Ok(Self { dtype, value })
104    }
105
106    /// Creates a new [`Scalar`] with the given [`DType`] and potentially null [`ScalarValue`]
107    /// without checking compatibility.
108    ///
109    /// # Safety
110    ///
111    /// The caller must ensure that the given [`DType`] and [`ScalarValue`] are compatible per the
112    /// rules defined in [`Self::validate`].
113    pub unsafe fn new_unchecked(dtype: DType, value: Option<ScalarValue>) -> Self {
114        #[cfg(debug_assertions)]
115        {
116            use vortex_error::VortexExpect;
117
118            Self::validate(&dtype, value.as_ref())
119                .vortex_expect("Scalar::new_unchecked called with incompatible dtype and value");
120        }
121
122        Self { dtype, value }
123    }
124
125    /// Returns a default value for the given [`DType`].
126    ///
127    /// For nullable types, this returns a null scalar. For non-nullable and non-nested types, this
128    /// returns the zero value for the type.
129    ///
130    /// See [`Scalar::zero_value`] for more details about "zero" values.
131    ///
132    /// For non-nullable nested types, this function recursively creates valid default children.
133    /// For a union specifically:
134    ///
135    /// - A nullable union defaults to an **outer null**. It has no selected variant or type ID.
136    /// - A non-nullable union selects its first variant. That selected child may itself default to
137    ///   an **inner null** when its dtype is nullable; the enclosing union remains non-null and
138    ///   retains the first variant's type ID.
139    ///
140    /// # Panics
141    ///
142    /// Panics if `dtype` has no default value.
143    pub fn default_value(dtype: &DType) -> Self {
144        Self::try_default_value(dtype)
145            .unwrap_or_else(|| vortex_panic!("{dtype} has no default value"))
146    }
147
148    /// Returns a valid default scalar, or [`None`] if `dtype` has no default.
149    pub(crate) fn try_default_value(dtype: &DType) -> Option<Self> {
150        let value = ScalarValue::try_default_value(dtype)?;
151        Self::try_new(dtype.clone(), value).ok()
152    }
153
154    /// Returns a non-null zero / identity value for the given [`DType`].
155    ///
156    /// # Zero Values
157    ///
158    /// Here is the list of non-null zero values for each [`DType`], regardless of its nullability:
159    ///
160    /// - `Null`: Does not have a "zero" value
161    /// - `Bool`: `false`
162    /// - `Primitive`: `0`
163    /// - `Decimal`: `0`
164    /// - `Utf8`: `""`
165    /// - `Binary`: An empty buffer
166    /// - `List`: An empty list
167    /// - `Map`: An empty map
168    /// - `FixedSizeList`: A list (with correct size) of zero values, which is determined by the
169    ///   element [`DType`]
170    /// - `Struct`: A struct where each field has a zero value, which is determined by the field
171    ///   [`DType`]
172    /// - `Union`: A non-null union selecting the first variant with a non-null child zero value
173    /// - `Extension`: The zero value of the storage [`DType`], if the extension accepts it.
174    ///
175    /// # Panics
176    ///
177    /// Panics if the dtype has no non-null zero value, such as `Null`, or if a nested dtype needed
178    /// to construct the zero value has no non-null zero value. An extension dtype has no zero
179    /// value if it rejects the zero value of its storage dtype.
180    ///
181    /// Unlike [`Scalar::default_value`], this never uses either an outer or inner null for a union:
182    /// even a nullable union's zero value is non-null and contains a non-null selected child.
183    pub fn zero_value(dtype: &DType) -> Self {
184        let value = ScalarValue::zero_value(dtype);
185
186        Self::try_new(dtype.clone(), Some(value))
187            .unwrap_or_else(|error| vortex_panic!("{dtype} has no non-null zero value: {error}"))
188    }
189
190    // Other methods.
191
192    /// Check if two scalars are equal, ignoring nullability of the [`DType`].
193    pub fn eq_ignore_nullability(&self, other: &Self) -> bool {
194        self.dtype.eq_ignore_nullability(&other.dtype) && self.value == other.value
195    }
196
197    /// Returns the parts of the [`Scalar`].
198    pub fn into_parts(self) -> (DType, Option<ScalarValue>) {
199        (self.dtype, self.value)
200    }
201
202    /// Returns the [`DType`] of the [`Scalar`].
203    pub fn dtype(&self) -> &DType {
204        &self.dtype
205    }
206
207    /// Returns an optional [`ScalarValue`] of the [`Scalar`], where `None` means the value is null.
208    pub fn value(&self) -> Option<&ScalarValue> {
209        self.value.as_ref()
210    }
211
212    /// Returns the internal optional [`ScalarValue`], where `None` means the value is null,
213    /// consuming the [`Scalar`].
214    pub fn into_value(self) -> Option<ScalarValue> {
215        self.value
216    }
217
218    /// Returns `true` if the [`Scalar`] has a non-null value.
219    pub fn is_valid(&self) -> bool {
220        self.value.is_some()
221    }
222
223    /// Returns `true` if the [`Scalar`] is null.
224    pub fn is_null(&self) -> bool {
225        self.value.is_none()
226    }
227
228    /// Returns `true` if the [`Scalar`] has a non-null zero value.
229    ///
230    /// Returns `None` if the scalar is null or its zero-ness is undefined. Otherwise, returns
231    /// `Some(true)` if the value is zero and `Some(false)` if it is not.
232    ///
233    /// A union that selects a variant other than the first returns `Some(false)`. A union selecting
234    /// its first variant delegates to that child's [`Scalar::is_zero`], so an inner null child
235    /// returns `None` and a non-null zero child returns `Some(true)`.
236    pub fn is_zero(&self) -> Option<bool> {
237        let value = self.value()?;
238
239        let is_zero = match self.dtype() {
240            DType::Null => {
241                vortex_panic!("non-null value somehow had `DType::Null`")
242            }
243            DType::Bool(_) => !value.as_bool(),
244            DType::Primitive(..) => value.as_primitive().is_zero(),
245            DType::Decimal(..) => value.as_decimal().is_zero(),
246            DType::Utf8(_) => value.as_utf8().is_empty(),
247            DType::Binary(_) => value.as_binary().is_empty(),
248            DType::List(..) => value.as_list().is_empty(),
249            DType::Map(..) => self.as_map().is_empty(),
250            // A fixed-size list is zero only if it has the expected number of elements and every
251            // element is itself a non-null zero value.1
252            DType::FixedSizeList(_, list_size, _) => {
253                let list = self.as_list();
254                list.len() == *list_size as usize
255                    && (0..list.len())
256                        .all(|i| list.element(i).is_some_and(|e| e.is_zero() == Some(true)))
257            }
258            // A struct is zero only if every one of its fields is itself a non-null zero value.
259            DType::Struct(..) => self
260                .as_struct()
261                .fields_iter()
262                .is_some_and(|mut fields| fields.all(|f| f.is_zero() == Some(true))),
263            // Only the first variant of unions can be zero. Its child determines whether the
264            // zero-ness is true, false, or undefined.
265            DType::Union(..) => {
266                let union = self.as_union();
267                if union.child_index() != Some(0) {
268                    false
269                } else {
270                    union.child().and_then(|child| child.is_zero())?
271                }
272            }
273            DType::Variant(_) => self.as_variant().is_zero()?,
274            DType::Extension(_) => self.as_extension().to_storage_scalar().is_zero()?,
275        };
276
277        Some(is_zero)
278    }
279
280    /// Reinterprets the bytes of this scalar as a different primitive type.
281    ///
282    /// # Errors
283    ///
284    /// Panics if the scalar is not a primitive type or if the types have different byte widths.
285    pub fn primitive_reinterpret_cast(&self, ptype: PType) -> VortexResult<Self> {
286        let primitive = self.as_primitive();
287        if primitive.ptype() == ptype {
288            return Ok(self.clone());
289        }
290
291        vortex_ensure_eq!(
292            primitive.ptype().byte_width(),
293            ptype.byte_width(),
294            "can't reinterpret cast between integers of two different widths"
295        );
296
297        Scalar::try_new(
298            DType::Primitive(ptype, self.dtype().nullability()),
299            primitive
300                .pvalue()
301                .map(|p| p.reinterpret_cast(ptype))
302                .map(ScalarValue::Primitive),
303        )
304    }
305
306    /// Returns an **ESTIMATE** of the size of the scalar in bytes, uncompressed.
307    ///
308    /// Note that the protobuf serialization of scalars will likely have a different (but roughly
309    /// similar) length.
310    pub fn approx_nbytes(&self) -> usize {
311        use crate::dtype::NativeDecimalType;
312        use crate::dtype::i256;
313
314        match self.dtype() {
315            DType::Null => 0,
316            DType::Bool(_) => 1,
317            DType::Primitive(ptype, _) => ptype.byte_width(),
318            DType::Decimal(dt, _) => {
319                if dt.precision() <= i128::MAX_PRECISION {
320                    size_of::<i128>()
321                } else {
322                    size_of::<i256>()
323                }
324            }
325            DType::Utf8(_) => self
326                .value()
327                .map_or_else(|| 0, |value| value.as_utf8().len()),
328            DType::Binary(_) => self
329                .value()
330                .map_or_else(|| 0, |value| value.as_binary().len()),
331            DType::List(..) | DType::FixedSizeList(..) => self
332                .as_list()
333                .elements()
334                .map(|fields| fields.into_iter().map(|f| f.approx_nbytes()).sum::<usize>())
335                .unwrap_or_default(),
336            DType::Map(..) => self
337                .as_map()
338                .entries()
339                .map(|(key, value)| key.approx_nbytes() + value.approx_nbytes())
340                .sum(),
341            DType::Struct(..) => self
342                .as_struct()
343                .fields_iter()
344                .map(|fields| fields.into_iter().map(|f| f.approx_nbytes()).sum::<usize>())
345                .unwrap_or_default(),
346            DType::Union(..) => self
347                .as_union()
348                .child()
349                .map_or(0, |value| 1 + value.approx_nbytes()),
350            DType::Variant(_) => self.as_variant().value().map_or(0, Scalar::approx_nbytes),
351            DType::Extension(_) => self.as_extension().to_storage_scalar().approx_nbytes(),
352        }
353    }
354}
355
356/// We implement `Hash` manually to be consistent with `PartialEq`. Since we ignore nullability in
357/// equality comparisons, we must also ignore it when hashing to maintain the invariant that equal
358/// values have equal hashes.
359impl Hash for Scalar {
360    fn hash<H: Hasher>(&self, state: &mut H) {
361        self.dtype.hash_ignore_nullability(state);
362        self.value.hash(state);
363    }
364}
365
366/// We implement `PartialEq` manually because we want to ignore nullability when comparing scalars.
367/// Two scalars with the same value but different nullability should be considered equal.
368///
369/// Note that this has **different** behavior than the [`PartialOrd`] implementation since the
370/// [`PartialOrd`] returns `None` if the types are different, whereas this `PartialEq`
371/// implementation simply returns `false`.
372impl PartialEq for Scalar {
373    fn eq(&self, other: &Self) -> bool {
374        self.dtype.eq_ignore_nullability(&other.dtype) && self.value == other.value
375    }
376}
377
378impl PartialOrd for Scalar {
379    /// Compares two scalar values for ordering.
380    ///
381    /// # Returns
382    /// - `Some(Ordering)` if both scalars have the same data type (ignoring nullability)
383    /// - `None` if the scalars have different data types
384    ///
385    /// # Ordering Rules
386    /// When types match, the ordering follows these rules:
387    /// - Null values are considered less than all non-null values
388    /// - Non-null values are compared according to their natural ordering
389    ///
390    /// # Examples
391    ///
392    /// ```
393    /// use std::cmp::Ordering;
394    /// use vortex_array::dtype::DType;
395    /// use vortex_array::dtype::Nullability;
396    /// use vortex_array::dtype::PType;
397    /// use vortex_array::scalar::Scalar;
398    ///
399    /// // Same types compare successfully
400    /// let a = Scalar::primitive(10i32, Nullability::NonNullable);
401    /// let b = Scalar::primitive(20i32, Nullability::NonNullable);
402    /// assert_eq!(a.partial_cmp(&b), Some(Ordering::Less));
403    ///
404    /// // Different types return None
405    /// let int_scalar = Scalar::primitive(10i32, Nullability::NonNullable);
406    /// let str_scalar = Scalar::utf8("hello", Nullability::NonNullable);
407    /// assert_eq!(int_scalar.partial_cmp(&str_scalar), None);
408    ///
409    /// // Nulls are less than non-nulls
410    /// let null = Scalar::null(DType::Primitive(PType::I32, Nullability::Nullable));
411    /// let value = Scalar::primitive(0i32, Nullability::Nullable);
412    /// assert_eq!(null.partial_cmp(&value), Some(Ordering::Less));
413    /// ```
414    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
415        if !self.dtype().eq_ignore_nullability(other.dtype()) {
416            return None;
417        }
418
419        partial_cmp_scalar_values(self.dtype(), self.value(), other.value())
420    }
421}
422
423/// Compare two optional scalar values using `dtype` for nested tuple interpretation.
424fn partial_cmp_scalar_values(
425    dtype: &DType,
426    lhs: Option<&ScalarValue>,
427    rhs: Option<&ScalarValue>,
428) -> Option<Ordering> {
429    match (lhs, rhs) {
430        (None, None) => Some(Ordering::Equal),
431        (None, Some(_)) => Some(Ordering::Less),
432        (Some(_), None) => Some(Ordering::Greater),
433        (Some(lhs), Some(rhs)) => partial_cmp_non_null_scalar_values(dtype, lhs, rhs),
434    }
435}
436
437/// Compare two non-null scalar values, consulting `dtype` only for tuple-backed values.
438fn partial_cmp_non_null_scalar_values(
439    dtype: &DType,
440    lhs: &ScalarValue,
441    rhs: &ScalarValue,
442) -> Option<Ordering> {
443    // `Scalar::validate` guarantees that a scalar's value matches its dtype. Most of the scalar
444    // value variants have only 1 method of comparison, regardless of the dtype.
445    match (lhs, rhs) {
446        (ScalarValue::Bool(lhs), ScalarValue::Bool(rhs)) => lhs.partial_cmp(rhs),
447        (ScalarValue::Primitive(lhs), ScalarValue::Primitive(rhs)) => lhs.partial_cmp(rhs),
448        (ScalarValue::Decimal(lhs), ScalarValue::Decimal(rhs)) => lhs.partial_cmp(rhs),
449        (ScalarValue::Utf8(lhs), ScalarValue::Utf8(rhs)) => lhs.partial_cmp(rhs),
450        (ScalarValue::Binary(lhs), ScalarValue::Binary(rhs)) => lhs.partial_cmp(rhs),
451        // `Tuple` is the exception here. Since it backs lists, fixed-size lists, and structs, we
452        // need the dtype to know whether children share one element dtype or use per-field dtypes.
453        (ScalarValue::Tuple(lhs), ScalarValue::Tuple(rhs)) => {
454            partial_cmp_tuple_values(dtype, lhs, rhs)
455        }
456        (ScalarValue::Union(lhs), ScalarValue::Union(rhs)) => {
457            if lhs.type_id() != rhs.type_id() {
458                return None;
459            }
460
461            let DType::Union(variants, _) = dtype else {
462                return None;
463            };
464            let child_index = variants.tag_to_child_index(lhs.type_id())?;
465            let child_dtype = variants.variant_by_index(child_index)?;
466
467            partial_cmp_scalar_values(&child_dtype, lhs.child_value(), rhs.child_value())
468        }
469        // Variant values can have a different dtype in each row, so it doesn't make sense to
470        // compare them.
471        (ScalarValue::Variant(_), ScalarValue::Variant(_)) => None,
472        _ => None,
473    }
474}
475
476/// Compare tuple values according to the list, fixed-size list, or struct dtype layout.
477fn partial_cmp_tuple_values(
478    dtype: &DType,
479    lhs: &[Option<ScalarValue>],
480    rhs: &[Option<ScalarValue>],
481) -> Option<Ordering> {
482    match dtype {
483        DType::List(element_dtype, _) | DType::FixedSizeList(element_dtype, ..) => {
484            partial_cmp_list_values(element_dtype, lhs, rhs)
485        }
486        DType::Struct(fields, _) => partial_cmp_struct_values(fields, lhs, rhs),
487        // A map compares as the list of its `{key, value}` entry structs.
488        DType::Map(map_dtype, _) => partial_cmp_list_values(&map_dtype.entries_dtype(), lhs, rhs),
489        DType::Extension(ext_dtype) => {
490            partial_cmp_tuple_values(ext_dtype.storage_dtype(), lhs, rhs)
491        }
492        _ => None,
493    }
494}
495
496/// Compare list tuple values using the shared element dtype for each element.
497fn partial_cmp_list_values(
498    element_dtype: &DType,
499    lhs: &[Option<ScalarValue>],
500    rhs: &[Option<ScalarValue>],
501) -> Option<Ordering> {
502    for (lhs, rhs) in lhs.iter().zip(rhs.iter()) {
503        match partial_cmp_scalar_values(element_dtype, lhs.as_ref(), rhs.as_ref())? {
504            Ordering::Equal => continue,
505            ordering => return Some(ordering),
506        }
507    }
508
509    Some(lhs.len().cmp(&rhs.len()))
510}
511
512/// Compare struct tuple values using each field's dtype in field order.
513fn partial_cmp_struct_values(
514    fields: &StructFields,
515    lhs: &[Option<ScalarValue>],
516    rhs: &[Option<ScalarValue>],
517) -> Option<Ordering> {
518    if lhs.len() != fields.nfields() || rhs.len() != fields.nfields() {
519        return None;
520    }
521
522    for ((field_dtype, lhs), rhs) in fields.field_dtypes().zip(lhs.iter()).zip(rhs.iter()) {
523        match partial_cmp_scalar_values(field_dtype, lhs.as_ref(), rhs.as_ref())? {
524            Ordering::Equal => continue,
525            ordering => return Some(ordering),
526        }
527    }
528
529    Some(Ordering::Equal)
530}
531
532#[cfg(test)]
533mod tests {
534    use std::cmp::Ordering;
535    use std::sync::Arc;
536
537    use rstest::rstest;
538    use vortex_error::VortexResult;
539
540    use crate::dtype::DType;
541    use crate::dtype::Nullability;
542    use crate::dtype::PType;
543    use crate::dtype::StructFields;
544    use crate::scalar::Scalar;
545
546    fn i32_scalar(value: i32) -> Scalar {
547        Scalar::primitive::<i32>(value, Nullability::NonNullable)
548    }
549
550    fn nullable_i32(value: Option<i32>) -> Scalar {
551        match value {
552            Some(value) => Scalar::primitive::<i32>(value, Nullability::Nullable),
553            None => Scalar::null(DType::Primitive(PType::I32, Nullability::Nullable)),
554        }
555    }
556
557    fn map_dtype(nullability: Nullability) -> VortexResult<DType> {
558        DType::map(
559            DType::Primitive(PType::I32, Nullability::NonNullable),
560            DType::Utf8(Nullability::Nullable),
561            false,
562            nullability,
563        )
564    }
565
566    fn map_scalar(entries: Vec<(i32, Option<&str>)>) -> VortexResult<Scalar> {
567        Scalar::try_map(
568            map_dtype(Nullability::Nullable)?,
569            entries.into_iter().map(|(key, value)| {
570                (
571                    i32_scalar(key),
572                    match value {
573                        Some(value) => Scalar::utf8(value, Nullability::Nullable),
574                        None => Scalar::null(DType::Utf8(Nullability::Nullable)),
575                    },
576                )
577            }),
578        )
579    }
580
581    /// Maps order entry-wise, then by entry count.
582    #[rstest]
583    #[case(vec![(1, Some("a"))], vec![(1, Some("a"))], Ordering::Equal)]
584    #[case(vec![(1, Some("a"))], vec![(1, Some("b"))], Ordering::Less)]
585    #[case(vec![(2, Some("a"))], vec![(1, Some("z"))], Ordering::Greater)]
586    #[case(vec![(1, Some("a"))], vec![(1, Some("a")), (2, Some("b"))], Ordering::Less)]
587    #[case(vec![], vec![], Ordering::Equal)]
588    #[case(vec![], vec![(1, Some("a"))], Ordering::Less)]
589    #[case(vec![(1, Some("a"))], vec![(1, None)], Ordering::Greater)]
590    fn map_ordering(
591        #[case] lhs: Vec<(i32, Option<&str>)>,
592        #[case] rhs: Vec<(i32, Option<&str>)>,
593        #[case] expected: Ordering,
594    ) -> VortexResult<()> {
595        assert_eq!(
596            map_scalar(lhs)?.partial_cmp(&map_scalar(rhs)?),
597            Some(expected)
598        );
599        Ok(())
600    }
601
602    #[test]
603    fn null_map_orders_before_every_non_null_map() -> VortexResult<()> {
604        let null = Scalar::null(map_dtype(Nullability::Nullable)?);
605
606        assert_eq!(null.partial_cmp(&map_scalar(vec![])?), Some(Ordering::Less));
607        assert_eq!(null.partial_cmp(&null), Some(Ordering::Equal));
608
609        Ok(())
610    }
611
612    fn ab_struct_dtype(nullability: Nullability) -> DType {
613        DType::Struct(
614            StructFields::new(
615                ["a", "b"].into(),
616                vec![
617                    DType::Primitive(PType::I32, Nullability::NonNullable),
618                    DType::Utf8(Nullability::NonNullable),
619                ],
620            ),
621            nullability,
622        )
623    }
624
625    #[rstest]
626    // A fixed-size list of all-zero elements is itself zero.
627    #[case(vec![0, 0], Some(true))]
628    #[case(vec![0], Some(true))]
629    // A single non-zero element makes the whole list non-zero. On `develop` these incorrectly
630    // returned `Some(true)` because only the element count was checked.
631    #[case(vec![0, 5], Some(false))]
632    #[case(vec![5, 0], Some(false))]
633    #[case(vec![1, 2], Some(false))]
634    fn fixed_size_list_is_zero(#[case] values: Vec<i32>, #[case] expected: Option<bool>) {
635        let element_dtype = DType::Primitive(PType::I32, Nullability::NonNullable);
636        let children: Vec<Scalar> = values.into_iter().map(i32_scalar).collect();
637        let scalar = Scalar::fixed_size_list(element_dtype, children, Nullability::NonNullable);
638        assert_eq!(scalar.is_zero(), expected);
639    }
640
641    #[test]
642    fn null_fixed_size_list_is_zero_is_none() {
643        let element_dtype = Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable));
644        let scalar = Scalar::null(DType::FixedSizeList(
645            element_dtype,
646            2,
647            Nullability::Nullable,
648        ));
649        assert_eq!(scalar.is_zero(), None);
650    }
651
652    #[test]
653    fn fixed_size_list_with_null_element_is_not_zero() {
654        // A non-null fixed-size list containing a null element is not a zero value. On `develop`
655        // this incorrectly returned `Some(true)`.
656        let element_dtype = DType::Primitive(PType::I32, Nullability::Nullable);
657        let children = vec![nullable_i32(Some(0)), nullable_i32(None)];
658        let scalar = Scalar::fixed_size_list(element_dtype, children, Nullability::NonNullable);
659        assert_eq!(scalar.is_zero(), Some(false));
660    }
661
662    #[test]
663    fn struct_with_all_zero_fields_is_zero() {
664        let scalar = Scalar::struct_(
665            ab_struct_dtype(Nullability::NonNullable),
666            vec![i32_scalar(0), Scalar::utf8("", Nullability::NonNullable)],
667        );
668        assert_eq!(scalar.is_zero(), Some(true));
669    }
670
671    #[rstest]
672    // A non-zero primitive field, a non-empty string field, or both, make the struct non-zero. On
673    // `develop` all of these incorrectly returned `Some(true)`.
674    #[case(5, "")]
675    #[case(0, "x")]
676    #[case(7, "y")]
677    fn struct_with_non_zero_field_is_not_zero(#[case] a: i32, #[case] b: &str) {
678        let scalar = Scalar::struct_(
679            ab_struct_dtype(Nullability::NonNullable),
680            vec![i32_scalar(a), Scalar::utf8(b, Nullability::NonNullable)],
681        );
682        assert_eq!(scalar.is_zero(), Some(false));
683    }
684
685    #[test]
686    fn null_struct_is_zero_is_none() {
687        let scalar = Scalar::null(ab_struct_dtype(Nullability::Nullable));
688        assert_eq!(scalar.is_zero(), None);
689    }
690
691    #[test]
692    fn struct_with_null_field_is_not_zero() {
693        // A non-null struct with a null field is not a zero value. On `develop` this incorrectly
694        // returned `Some(true)`.
695        let dtype = DType::Struct(
696            StructFields::new(
697                ["a", "b"].into(),
698                vec![
699                    DType::Primitive(PType::I32, Nullability::Nullable),
700                    DType::Primitive(PType::I32, Nullability::Nullable),
701                ],
702            ),
703            Nullability::NonNullable,
704        );
705        let scalar = Scalar::struct_(dtype, vec![nullable_i32(Some(0)), nullable_i32(None)]);
706        assert_eq!(scalar.is_zero(), Some(false));
707    }
708
709    #[test]
710    fn nested_struct_of_fixed_size_list_recurses() {
711        // Zero-checking must recurse through both structs and fixed-size lists. On `develop` the
712        // non-zero case incorrectly returned `Some(true)`.
713        let element_dtype = Arc::new(DType::Primitive(PType::I32, Nullability::NonNullable));
714        let fsl_dtype =
715            DType::FixedSizeList(Arc::clone(&element_dtype), 2, Nullability::NonNullable);
716        let struct_dtype = DType::Struct(
717            StructFields::new(["fsl"].into(), vec![fsl_dtype]),
718            Nullability::NonNullable,
719        );
720
721        let all_zero = Scalar::struct_(
722            struct_dtype.clone(),
723            vec![Scalar::fixed_size_list(
724                Arc::clone(&element_dtype),
725                vec![i32_scalar(0), i32_scalar(0)],
726                Nullability::NonNullable,
727            )],
728        );
729        assert_eq!(all_zero.is_zero(), Some(true));
730
731        let with_non_zero = Scalar::struct_(
732            struct_dtype,
733            vec![Scalar::fixed_size_list(
734                element_dtype,
735                vec![i32_scalar(0), i32_scalar(9)],
736                Nullability::NonNullable,
737            )],
738        );
739        assert_eq!(with_non_zero.is_zero(), Some(false));
740    }
741}