Feature: add zero and null constructors for scalars (#5705)

I need this to help with implementing all of the `Cast` logic.

Signed-off-by: Connor Tsui <[email protected]>

Author: connortsui20

vortex-buffer/src/string.rs

@@ -23,6 +23,11 @@ impl BufferString {
         Self(buffer)
     }
 
+    /// Creates an empty `BufferString`.
+    pub fn empty() -> Self {
+        Self(ByteBuffer::from(vec![]))
+    }
+
     /// Return a view of the contents of BufferString as an immutable `&str`.
     pub fn as_str(&self) -> &str {
         // SAFETY: We have already validated that the buffer is valid UTF-8

vortex-vector/src/binaryview/scalar.rs

@@ -23,10 +23,20 @@ impl<T: BinaryViewType> BinaryViewScalar<T> {
 }
 
 impl<T: BinaryViewType> BinaryViewScalar<T> {
-    /// Returns the scalar value as [`BinaryViewType::Scalar`], or `None` if the scalar is null.
+    /// Returns the scalar value as [`BinaryViewType::Scalar`], or [`None`] if the scalar is null.
     pub fn value(&self) -> Option<&T::Scalar> {
         self.0.as_ref()
     }
+
+    /// Creates a zero (empty) binary view scalar.
+    pub fn zero() -> Self {
+        Self::new(Some(T::empty_scalar()))
+    }
+
+    /// Creates a null binary view scalar.
+    pub fn null() -> Self {
+        Self::new(None)
+    }
 }
 
 impl<T: BinaryViewType> ScalarOps for BinaryViewScalar<T> {

vortex-vector/src/binaryview/types.rs

@@ -7,6 +7,7 @@ use std::fmt::Debug;
 
 use vortex_buffer::BufferString;
 use vortex_buffer::ByteBuffer;
+use vortex_dtype::DType;
 
 use crate::Vector;
 use crate::VectorMut;
@@ -60,9 +61,15 @@ pub trait BinaryViewType: Debug + Sized + Send + Sync + 'static + private::Seale
 
     /// Upcast a type-specific instance to a generic instance.
     fn upcast<V: BinaryViewTypeUpcast>(input: V::Input<Self>) -> V;
+
+    /// Returns an empty scalar value.
+    fn empty_scalar() -> Self::Scalar;
+
+    /// Returns true if the given dtype matches this binary view type.
+    fn matches_dtype(dtype: &DType) -> bool;
 }
 
-/// [`BinaryType`] for UTF-8 strings.
+/// [`BinaryViewType`] for UTF-8 strings.
 #[derive(Clone, Debug)]
 pub struct StringType;
 impl BinaryViewType for StringType {
@@ -82,7 +89,7 @@ impl BinaryViewType for StringType {
     }
 
     #[inline(always)]
-    unsafe fn scalar_from_buffer_unchecked(buffer: ByteBuffer) -> Self::Scalar {
+    unsafe fn scalar_from_buffer_unchecked(buffer: ByteBuffer) -> BufferString {
         unsafe { BufferString::new_unchecked(buffer) }
     }
 
@@ -93,9 +100,17 @@ impl BinaryViewType for StringType {
     fn upcast<V: BinaryViewTypeUpcast>(input: V::Input<Self>) -> V {
         V::from_string(input)
     }
+
+    fn empty_scalar() -> BufferString {
+        BufferString::empty()
+    }
+
+    fn matches_dtype(dtype: &DType) -> bool {
+        matches!(dtype, DType::Utf8(_))
+    }
 }
 
-/// [`BinaryType`] for raw binary data.
+/// [`BinaryViewType`] for raw binary data.
 #[derive(Clone, Debug)]
 pub struct BinaryType;
 impl BinaryViewType for BinaryType {
@@ -113,7 +128,7 @@ impl BinaryViewType for BinaryType {
     }
 
     #[inline(always)]
-    unsafe fn scalar_from_buffer_unchecked(buffer: ByteBuffer) -> Self::Scalar {
+    unsafe fn scalar_from_buffer_unchecked(buffer: ByteBuffer) -> ByteBuffer {
         buffer
     }
 
@@ -124,6 +139,14 @@ impl BinaryViewType for BinaryType {
     fn upcast<V: BinaryViewTypeUpcast>(input: V::Input<Self>) -> V {
         V::from_binary(input)
     }
+
+    fn empty_scalar() -> ByteBuffer {
+        ByteBuffer::empty()
+    }
+
+    fn matches_dtype(dtype: &DType) -> bool {
+        matches!(dtype, DType::Binary(_))
+    }
 }
 
 /// Trait for downcasting generic variable binary types to specific types.

vortex-vector/src/bool/scalar.rs

@@ -21,6 +21,16 @@ impl BoolScalar {
     pub fn value(&self) -> Option<bool> {
         self.0
     }
+
+    /// Creates a zero (false) bool scalar.
+    pub fn zero() -> Self {
+        Self::new(Some(false))
+    }
+
+    /// Creates a null bool scalar.
+    pub fn null() -> Self {
+        Self::new(None)
+    }
 }
 
 impl ScalarOps for BoolScalar {

vortex-vector/src/decimal/scalar.rs

@@ -1,11 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
+use vortex_dtype::DecimalDType;
+use vortex_dtype::DecimalType;
 use vortex_dtype::DecimalTypeDowncast;
 use vortex_dtype::DecimalTypeUpcast;
 use vortex_dtype::NativeDecimalType;
 use vortex_dtype::PrecisionScale;
 use vortex_dtype::i256;
+use vortex_dtype::match_each_decimal_value_type;
 use vortex_error::VortexExpect;
 use vortex_error::vortex_panic;
 
@@ -56,6 +59,22 @@ impl DecimalScalar {
             DecimalScalar::D256(v) => v.ps.scale(),
         }
     }
+
+    /// Creates a zero decimal scalar of the given [`DecimalDType`].
+    pub fn zero(decimal_dtype: &DecimalDType) -> Self {
+        let decimal_type = DecimalType::smallest_decimal_value_type(decimal_dtype);
+        match_each_decimal_value_type!(decimal_type, |D| {
+            DScalar::<D>::zero(decimal_dtype).into()
+        })
+    }
+
+    /// Creates a null decimal scalar of the given [`DecimalDType`].
+    pub fn null(decimal_dtype: &DecimalDType) -> Self {
+        let decimal_type = DecimalType::smallest_decimal_value_type(decimal_dtype);
+        match_each_decimal_value_type!(decimal_type, |D| {
+            DScalar::<D>::null(decimal_dtype).into()
+        })
+    }
 }
 
 impl ScalarOps for DecimalScalar {
@@ -135,6 +154,20 @@ impl<D: NativeDecimalType> DScalar<D> {
     pub fn value(&self) -> Option<D> {
         self.value
     }
+
+    /// Creates a zero decimal scalar of the given [`DecimalDType`].
+    pub fn zero(decimal_dtype: &DecimalDType) -> Self {
+        let ps = PrecisionScale::<D>::new(decimal_dtype.precision(), decimal_dtype.scale());
+        // SAFETY: Zero (default) is always valid for any precision/scale.
+        unsafe { DScalar::<D>::new_unchecked(ps, Some(D::default())) }
+    }
+
+    /// Creates a null decimal scalar of the given [`DecimalDType`].
+    pub fn null(decimal_dtype: &DecimalDType) -> Self {
+        let ps = PrecisionScale::<D>::new(decimal_dtype.precision(), decimal_dtype.scale());
+        // SAFETY: None is always valid for any precision/scale.
+        unsafe { DScalar::<D>::new_unchecked(ps, None) }
+    }
 }
 
 impl<D: NativeDecimalType> ScalarOps for DScalar<D> {

vortex-vector/src/fixed_size_list/scalar.rs

@@ -1,23 +1,27 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
+use vortex_dtype::DType;
+use vortex_error::vortex_panic;
+use vortex_mask::Mask;
+
 use crate::Scalar;
 use crate::ScalarOps;
 use crate::VectorMut;
+use crate::VectorMutOps;
 use crate::VectorOps;
 use crate::fixed_size_list::FixedSizeListVector;
-use vortex_mask::Mask;
 
 /// A scalar value for fixed-size list types.
 ///
-/// The inner value is a length-1 fsl vector.
+/// The inner value is a length-1 [`FixedSizeListVector`].
 // NOTE(ngates): the reason we don't hold Option<Vector> representing the elements is that we
 //  wouldn't be able to go back to a vector using "repeat".
 #[derive(Clone, Debug)]
 pub struct FixedSizeListScalar(FixedSizeListVector);
 
 impl FixedSizeListScalar {
-    /// Create a new FixedSizeListScalar from a length-1 FixedSizeListVector.
+    /// Create a new [`FixedSizeListScalar`] from a length-1 [`FixedSizeListVector`].
     ///
     /// # Panics
     ///
@@ -33,6 +37,42 @@ impl FixedSizeListScalar {
     }
 }
 
+impl FixedSizeListScalar {
+    /// Creates a zero (default elements) fixed-size list scalar of the given [`DType`].
+    ///
+    /// # Panics
+    ///
+    /// Panics if the dtype is not a [`DType::FixedSizeList`].
+    pub fn zero(dtype: &DType) -> Self {
+        if !matches!(dtype, DType::FixedSizeList(..)) {
+            vortex_panic!("Expected FixedSizeList dtype, got {}", dtype);
+        }
+
+        let mut vec = VectorMut::with_capacity(dtype, 1);
+        vec.append_zeros(1);
+        vec.freeze().scalar_at(0).into_fixed_size_list()
+    }
+
+    /// Creates a null fixed-size list scalar of the given [`DType`].
+    ///
+    /// # Panics
+    ///
+    /// Panics if the dtype is not a nullable [`DType::FixedSizeList`].
+    pub fn null(dtype: &DType) -> Self {
+        match dtype {
+            DType::FixedSizeList(_, _, n) if n.is_nullable() => {}
+            DType::FixedSizeList(..) => {
+                vortex_panic!("Expected nullable FixedSizeList dtype, got {}", dtype)
+            }
+            _ => vortex_panic!("Expected FixedSizeList dtype, got {}", dtype),
+        }
+
+        let mut vec = VectorMut::with_capacity(dtype, 1);
+        vec.append_nulls(1);
+        vec.freeze().scalar_at(0).into_fixed_size_list()
+    }
+}
+
 impl ScalarOps for FixedSizeListScalar {
     fn is_valid(&self) -> bool {
         self.0.validity().value(0)

vortex-vector/src/listview/scalar.rs

@@ -1,24 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
+use std::sync::Arc;
+
+use vortex_dtype::DType;
+use vortex_error::vortex_panic;
+use vortex_mask::Mask;
+use vortex_mask::MaskMut;
+
 use crate::Scalar;
 use crate::ScalarOps;
 use crate::VectorMut;
+use crate::VectorMutOps;
 use crate::VectorOps;
 use crate::listview::ListViewVector;
 use crate::listview::ListViewVectorMut;
-use std::sync::Arc;
-use vortex_mask::Mask;
-use vortex_mask::MaskMut;
 
 /// A scalar value for list view types.
 ///
-/// The inner value is a ListViewVector with length 1.
+/// The inner value is a [`ListViewVector`] with length 1.
 #[derive(Clone, Debug)]
 pub struct ListViewScalar(ListViewVector);
 
 impl ListViewScalar {
-    /// Create a new ListViewScalar from a length-1 ListViewVector.
+    /// Create a new [`ListViewScalar`] from a length-1 [`ListViewVector`].
     ///
     /// # Panics
     ///
@@ -34,6 +39,40 @@ impl ListViewScalar {
     }
 }
 
+impl ListViewScalar {
+    /// Creates a zero (empty list) list view scalar of the given [`DType`].
+    ///
+    /// # Panics
+    ///
+    /// Panics if the dtype is not a [`DType::List`].
+    pub fn zero(dtype: &DType) -> Self {
+        if !matches!(dtype, DType::List(..)) {
+            vortex_panic!("Expected List dtype, got {}", dtype);
+        }
+
+        let mut vec = VectorMut::with_capacity(dtype, 1);
+        vec.append_zeros(1);
+        vec.freeze().scalar_at(0).into_list()
+    }
+
+    /// Creates a null list view scalar of the given [`DType`].
+    ///
+    /// # Panics
+    ///
+    /// Panics if the dtype is not a nullable [`DType::List`].
+    pub fn null(dtype: &DType) -> Self {
+        match dtype {
+            DType::List(_, n) if n.is_nullable() => {}
+            DType::List(..) => vortex_panic!("Expected nullable List dtype, got {}", dtype),
+            _ => vortex_panic!("Expected List dtype, got {}", dtype),
+        }
+
+        let mut vec = VectorMut::with_capacity(dtype, 1);
+        vec.append_nulls(1);
+        vec.freeze().scalar_at(0).into_list()
+    }
+}
+
 impl ScalarOps for ListViewScalar {
     fn is_valid(&self) -> bool {
         self.0.validity().value(0)

vortex-vector/src/primitive/scalar.rs

@@ -8,6 +8,7 @@ use vortex_dtype::PType;
 use vortex_dtype::PTypeDowncast;
 use vortex_dtype::PTypeUpcast;
 use vortex_dtype::half::f16;
+use vortex_dtype::match_each_native_ptype;
 use vortex_error::VortexExpect;
 use vortex_error::vortex_panic;
 
@@ -63,6 +64,16 @@ impl PrimitiveScalar {
             PrimitiveScalar::F64(_) => PType::F64,
         }
     }
+
+    /// Creates a zero primitive scalar of the given [`PType`].
+    pub fn zero(ptype: PType) -> Self {
+        match_each_native_ptype!(ptype, |T| { PScalar::<T>::zero().into() })
+    }
+
+    /// Creates a null primitive scalar of the given [`PType`].
+    pub fn null(ptype: PType) -> Self {
+        match_each_native_ptype!(ptype, |T| { PScalar::<T>::null().into() })
+    }
 }
 
 impl ScalarOps for PrimitiveScalar {
@@ -111,6 +122,16 @@ impl<T: NativePType> PScalar<T> {
     pub fn value(&self) -> Option<T> {
         self.0
     }
+
+    /// Creates a zero primitive scalar.
+    pub fn zero() -> Self {
+        Self::new(Some(T::default()))
+    }
+
+    /// Creates a null primitive scalar.
+    pub fn null() -> Self {
+        Self::new(None)
+    }
 }
 
 impl<T: NativePType> From<PScalar<T>> for PrimitiveScalar {

vortex-vector/src/private.rs

@@ -7,6 +7,9 @@
 //! Sealing these traits prevents external crates from implementing them while still allowing public
 //! usage, which gives us the freedom to add new trait methods in the future without breaking
 //! backward compatibility.
+//!
+//! [`VectorOps`]: crate::VectorOps
+//! [`VectorMutOps`]: crate::VectorMutOps
 
 use vortex_dtype::NativeDecimalType;
 use vortex_dtype::NativePType;