Additions to vector API (#5045)

Author: gatesn

Cargo.lock

@@ -322,11 +322,11 @@ impl BitOr for &BitBuffer {
     }
 }
 
-impl BitOr for BitBuffer {
+impl BitOr<&BitBuffer> for BitBuffer {
     type Output = BitBuffer;
 
-    fn bitor(self, rhs: Self) -> Self::Output {
-        (&self).bitor(&rhs)
+    fn bitor(self, rhs: &BitBuffer) -> Self::Output {
+        (&self).bitor(rhs)
     }
 }
 
@@ -338,11 +338,11 @@ impl BitAnd for &BitBuffer {
     }
 }
 
-impl BitAnd for BitBuffer {
+impl BitAnd<&BitBuffer> for BitBuffer {
     type Output = BitBuffer;
 
-    fn bitand(self, rhs: Self) -> Self::Output {
-        (&self).bitand(&rhs)
+    fn bitand(self, rhs: &BitBuffer) -> Self::Output {
+        (&self).bitand(rhs)
     }
 }
 
@@ -370,11 +370,21 @@ impl BitXor for &BitBuffer {
     }
 }
 
-impl BitXor for BitBuffer {
+impl BitXor<&BitBuffer> for BitBuffer {
     type Output = BitBuffer;
 
-    fn bitxor(self, rhs: Self) -> Self::Output {
-        (&self).bitxor(&rhs)
+    fn bitxor(self, rhs: &BitBuffer) -> Self::Output {
+        (&self).bitxor(rhs)
+    }
+}
+
+impl BitBuffer {
+    /// Create a new BitBuffer by performing a bitwise AND NOT operation between two BitBuffers.
+    ///
+    /// This operation is sufficiently common that we provide a dedicated method for it avoid
+    /// making two passes over the data.
+    pub fn bitand_not(&self, rhs: &BitBuffer) -> BitBuffer {
+        bitwise_binary_op(self, rhs, |a, b| a & !b)
     }
 }
 

vortex-buffer/src/bit/buf.rs

@@ -2,8 +2,18 @@
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
 /// A macro for constructing bit-buffers akin to `vec![..]`.
+///
+/// Supports multiple syntaxes:
+/// - `bitbuffer![]` - empty buffer
+/// - `bitbuffer![value; count]` - fill with value
+/// - `bitbuffer![expr, expr, ...]` - comma-separated boolean expressions
+/// - `bitbuffer![0 1 0 1]` - space-separated bit literals (0s and 1s)
 #[macro_export]
 macro_rules! bitbuffer {
+    // Internal rule to convert a single bit (0 or 1) to bool
+    (@bit 0) => { false };
+    (@bit 1) => { true };
+
     () => (
         $crate::BitBuffer::empty()
     );
@@ -13,11 +23,25 @@ macro_rules! bitbuffer {
     ($($x:expr),+ $(,)?) => (
         $crate::BitBuffer::from_iter([$($x),+])
     );
+    // Match space-separated bit literals (0 or 1)
+    ($($bit:tt)+) => {
+        $crate::BitBuffer::from_iter([$( $crate::bitbuffer!(@bit $bit) ),+])
+    };
 }
 
 /// A macro for constructing bit-buffers akin to `vec![..]`.
+///
+/// Supports multiple syntaxes:
+/// - `bitbuffer_mut![]` - empty buffer
+/// - `bitbuffer_mut![value; count]` - fill with value
+/// - `bitbuffer_mut![expr, expr, ...]` - comma-separated boolean expressions
+/// - `bitbuffer_mut![0 1 0 1]` - space-separated bit literals (0s and 1s)
 #[macro_export]
 macro_rules! bitbuffer_mut {
+    // Internal rule to convert a single bit (0 or 1) to bool
+    (@bit 0) => { false };
+    (@bit 1) => { true };
+
     () => (
         $crate::BitBufferMut::empty()
     );
@@ -27,4 +51,8 @@ macro_rules! bitbuffer_mut {
     ($($x:expr),+ $(,)?) => (
         $crate::BitBufferMut::from_iter([$($x),+])
     );
+    // Match space-separated bit literals (0 or 1)
+    ($($bit:tt)+) => {
+        $crate::BitBufferMut::from_iter([$( $crate::bitbuffer_mut!(@bit $bit) ),+])
+    };
 }

vortex-buffer/src/bit/macros.rs

@@ -143,10 +143,7 @@ pub trait NativePType:
     fn is_eq(self, other: Self) -> bool;
 
     /// Downcast the provided object to a type-specific instance.
-    fn downcast<V: PTypeDowncast + ?Sized>(visitor: &V) -> V::Output<Self>;
-
-    /// Downcast the provided object to a type-specific instance.
-    fn downcast_mut<V: PTypeDowncastMut + ?Sized>(visitor: &mut V) -> V::Output<Self>;
+    fn downcast<V: PTypeDowncast>(visitor: V) -> V::Output<Self>;
 
     /// Upcast a type-specific instance to a generic instance.
     fn upcast<V: PTypeUpcast>(input: V::Input<Self>) -> V;
@@ -157,65 +154,37 @@ pub trait NativePType:
 pub trait PTypeDowncast {
     type Output<T: NativePType>;
 
-    fn as_u8(&self) -> Self::Output<u8>;
-    fn as_u16(&self) -> Self::Output<u16>;
-    fn as_u32(&self) -> Self::Output<u32>;
-    fn as_u64(&self) -> Self::Output<u64>;
-    fn as_i8(&self) -> Self::Output<i8>;
-    fn as_i16(&self) -> Self::Output<i16>;
-    fn as_i32(&self) -> Self::Output<i32>;
-    fn as_i64(&self) -> Self::Output<i64>;
-    fn as_f16(&self) -> Self::Output<f16>;
-    fn as_f32(&self) -> Self::Output<f32>;
-    fn as_f64(&self) -> Self::Output<f64>;
+    fn into_u8(self) -> Self::Output<u8>;
+    fn into_u16(self) -> Self::Output<u16>;
+    fn into_u32(self) -> Self::Output<u32>;
+    fn into_u64(self) -> Self::Output<u64>;
+    fn into_i8(self) -> Self::Output<i8>;
+    fn into_i16(self) -> Self::Output<i16>;
+    fn into_i32(self) -> Self::Output<i32>;
+    fn into_i64(self) -> Self::Output<i64>;
+    fn into_f16(self) -> Self::Output<f16>;
+    fn into_f32(self) -> Self::Output<f32>;
+    fn into_f64(self) -> Self::Output<f64>;
 }
 
 /// Extension trait to provide generic downcasting for [`PTypeDowncast`].
 pub trait PTypeDowncastExt: PTypeDowncast {
     /// Downcast the object to a specific primitive type.
-    fn as_primitive<T: NativePType>(&self) -> Self::Output<T> {
+    fn into_primitive<T: NativePType>(self) -> Self::Output<T>
+    where
+        Self: Sized,
+    {
         T::downcast(self)
     }
 }
 
-impl<T: PTypeDowncast + ?Sized> PTypeDowncastExt for T {}
-
-/// A visitor trait for converting a `NativePType` to another mutable parameterized type.
-#[allow(missing_docs)] // Kind of obvious..
-pub trait PTypeDowncastMut {
-    type Output<T: NativePType>;
-
-    fn as_u8(&mut self) -> Self::Output<u8>;
-    fn as_u16(&mut self) -> Self::Output<u16>;
-    fn as_u32(&mut self) -> Self::Output<u32>;
-    fn as_u64(&mut self) -> Self::Output<u64>;
-    fn as_i8(&mut self) -> Self::Output<i8>;
-    fn as_i16(&mut self) -> Self::Output<i16>;
-    fn as_i32(&mut self) -> Self::Output<i32>;
-    fn as_i64(&mut self) -> Self::Output<i64>;
-    fn as_f16(&mut self) -> Self::Output<f16>;
-    fn as_f32(&mut self) -> Self::Output<f32>;
-    fn as_f64(&mut self) -> Self::Output<f64>;
-}
-
-/// Extension trait to provide generic downcasting for [`PTypeDowncastMut`].
-pub trait PTypeDowncastMutExt: PTypeDowncastMut {
-    /// Downcast the object to a specific primitive type.
-    fn as_primitive_mut<T: NativePType>(&mut self) -> Self::Output<T> {
-        T::downcast_mut(self)
-    }
-}
+impl<T: PTypeDowncast> PTypeDowncastExt for T {}
 
 macro_rules! impl_ptype_downcast {
     ($T:ty) => {
         #[inline]
-        fn downcast<V: PTypeDowncast + ?Sized>(visitor: &V) -> V::Output<Self> {
-            paste::paste! { visitor.[<as_ $T>]() }
-        }
-
-        #[inline]
-        fn downcast_mut<V: PTypeDowncastMut + ?Sized>(visitor: &mut V) -> V::Output<Self> {
-            paste::paste! { visitor.[<as_ $T>]() }
+        fn downcast<V: PTypeDowncast>(visitor: V) -> V::Output<Self> {
+            paste::paste! { visitor.[<into_ $T>]() }
         }
 
         #[inline]
@@ -279,8 +248,6 @@ macro_rules! native_ptype {
     };
 }
 
-impl<T: PTypeDowncastMut + ?Sized> PTypeDowncastMutExt for T {}
-
 macro_rules! native_float_ptype {
     ($T:ty, $ptype:tt) => {
         impl crate::NativeDType for $T {

vortex-dtype/src/ptype.rs

@@ -28,6 +28,11 @@ enum Inner {
 }
 
 impl MaskMut {
+    /// Creates a new empty mask.
+    pub fn empty() -> Self {
+        Self::with_capacity(0)
+    }
+
     /// Creates a new empty mask with the default capacity.
     pub fn with_capacity(capacity: usize) -> Self {
         Self(Inner::Empty { capacity })

vortex-mask/src/mask_mut.rs

@@ -24,4 +24,3 @@ vortex-buffer = { workspace = true }
 vortex-dtype = { workspace = true }
 vortex-error = { workspace = true }
 vortex-mask = { workspace = true }
-vortex-scalar = { workspace = true }

vortex-vector/Cargo.toml

@@ -23,12 +23,32 @@ pub struct BoolVector {
     pub(super) validity: Mask,
 }
 
+impl BoolVector {
+    /// Creates a new [`BoolVector`] from the given bits and validity mask.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the length of the validity mask does not match the length of the bits.
+    pub fn new(bits: BitBuffer, validity: Mask) -> Self {
+        assert_eq!(
+            validity.len(),
+            bits.len(),
+            "BoolVector validity mask must have the same length as bits"
+        );
+        Self { bits, validity }
+    }
+
+    /// Returns the bits buffer of the boolean vector.
+    pub fn bits(&self) -> &BitBuffer {
+        &self.bits
+    }
+}
+
 impl VectorOps for BoolVector {
     type Mutable = BoolVectorMut;
 
     fn len(&self) -> usize {
         debug_assert!(self.validity.len() == self.bits.len());
-
         self.bits.len()
     }
 

vortex-vector/src/bool/vector.rs

@@ -11,23 +11,18 @@
 #![deny(clippy::missing_panics_doc)]
 #![deny(clippy::missing_safety_doc)]
 
-mod vector;
-pub use vector::Vector;
-
-mod vector_mut;
-pub use vector_mut::VectorMut;
-
-mod ops;
-pub use ops::{VectorMutOps, VectorOps};
-
 mod bool;
+mod macros;
 mod null;
+mod ops;
 mod primitive;
+mod private;
+mod vector;
+mod vector_mut;
 
 pub use bool::{BoolVector, BoolVectorMut};
 pub use null::{NullVector, NullVectorMut};
+pub use ops::{VectorMutOps, VectorOps};
 pub use primitive::{PVector, PVectorMut, PrimitiveVector, PrimitiveVectorMut};
-
-mod macros;
-
-mod private;
+pub use vector::Vector;
+pub use vector_mut::VectorMut;

vortex-vector/src/lib.rs

@@ -75,7 +75,7 @@ pub trait VectorMutOps: private::Sealed + Into<VectorMut> {
     /// Appends `n` null elements to the vector.
     ///
     /// Implementors should ensure that they correctly append "null" or garbage values to their
-    /// elements in addition to adding nulls to their validity mask.s.
+    /// elements in addition to adding nulls to their validity mask.
     fn append_nulls(&mut self, n: usize);
 
     /// Converts `self` into an immutable vector.