Trait MaskedArray

Source

pub trait MaskedArray {
    type T: Default + PartialEq + Clone + Copy;
    type Container;
    type LogicalType: Default;
    type CopyType: Default;

Show 36 methods    // Required methods
    fn len(&self) -> usize;
    fn data(&self) -> &Self::Container;
    fn data_mut(&mut self) -> &mut Self::Container;
    fn get(&self, idx: usize) -> Option<Self::CopyType>;
    fn set(&mut self, idx: usize, value: Self::LogicalType);
    unsafe fn get_unchecked(&self, idx: usize) -> Option<Self::CopyType>;
    unsafe fn set_unchecked(&mut self, idx: usize, value: Self::LogicalType);
    fn iter(&self) -> impl Iterator<Item = Self::CopyType>;
    fn iter_opt(&self) -> impl Iterator<Item = Option<Self::CopyType>>;
    fn iter_range(
        &self,
        offset: usize,
        len: usize,
    ) -> impl Iterator<Item = Self::CopyType>;
    fn iter_opt_range(
        &self,
        offset: usize,
        len: usize,
    ) -> impl Iterator<Item = Option<Self::CopyType>>;
    fn push(&mut self, value: Self::LogicalType);
    unsafe fn push_unchecked(&mut self, value: Self::LogicalType);
    fn slice_clone(&self, offset: usize, len: usize) -> Self;
    fn resize(&mut self, n: usize, value: Self::LogicalType);
    fn null_mask(&self) -> Option<&Bitmask>;
    fn null_mask_mut(&mut self) -> Option<&mut Bitmask>;
    fn set_null_mask(&mut self, mask: Option<Bitmask>);
    fn append_array(&mut self, other: &Self);
    fn append_range(
        &mut self,
        other: &Self,
        offset: usize,
        len: usize,
    ) -> Result<(), MinarrowError>;
    fn insert_rows(
        &mut self,
        index: usize,
        other: &Self,
    ) -> Result<(), MinarrowError>;
    fn split(self, index: usize) -> Result<(Self, Self), MinarrowError>
       where Self: Sized;
    fn extend_from_iter_with_capacity<I>(
        &mut self,
        iter: I,
        additional_capacity: usize,
    )
       where I: Iterator<Item = Self::LogicalType>;
    fn extend_from_slice(&mut self, slice: &[Self::LogicalType]);
    fn fill(value: Self::LogicalType, count: usize) -> Self;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn tuple_ref(&self, offset: usize, len: usize) -> (&Self, usize, usize) { ... }
    fn is_null(&self, idx: usize) -> bool { ... }
    fn is_nullable(&self) -> bool { ... }
    fn null_count(&self) -> usize { ... }
    fn push_null(&mut self) { ... }
    unsafe fn push_null_unchecked(&mut self) { ... }
    fn set_null(&mut self, idx: usize) { ... }
    unsafe fn set_null_unchecked(&mut self, idx: usize) { ... }
    fn push_nulls(&mut self, n: usize) { ... }
    unsafe fn push_nulls_unchecked(&mut self, n: usize) { ... }
}

Expand description

§MaskedArray

MaskedArray is implemented by all inner, nullable arrays.

§Purpose

MaskedArray ensures interface consistency across BooleanArray, CategoricalArray, DatetimeArray, FloatArray, IntegerArray and StringArray.
It avoids repeition through default boilerplate implementations, focusing on null value handling.
This serves to enforce the base pattern contract, and is either overriden on non-fixed width types (e.g., BooleanArray, StringArray), or, for fixed width types (e.g., FloatArray, IntegerArray), is supported by macros.

Required Associated Types§

Source

type T: Default + PartialEq + Clone + Copy

The element type (e.g. f32, bool, etc.) Or, utility type e.g., Offsets for cases like String

Source

type Container

The backing store (e.g. Vec64<Self::Elem> or Bitmask)

Source

type LogicalType: Default

The logical type that the data carries

Source

type CopyType: Default

The type that implements Copy (e.g., &str)

Required Methods§

Source

fn len(&self) -> usize

The below methods differ for the Boolean (bit-packed), and String (variable-length) variants and thus are implemented via macros for the standard variants, and then implemented on those types directly

Returns the number of elements in the array.

Source

fn data(&self) -> &Self::Container

Returns a reference to the underlying data.

Source

fn data_mut(&mut self) -> &mut Self::Container

Returns a mutable reference to the underlying data.

Source

fn get(&self, idx: usize) -> Option<Self::CopyType>

Retrieves the value at the given index, or None if null or beyond length.

Source

fn set(&mut self, idx: usize, value: Self::LogicalType)

Sets the value at the given index, updating the null‐mask.

Source

unsafe fn get_unchecked(&self, idx: usize) -> Option<Self::CopyType>

Like get, but skips the idx >= len() check.

Source

unsafe fn set_unchecked(&mut self, idx: usize, value: Self::LogicalType)

Like set, but skips bounds checks.

Source

fn iter(&self) -> impl Iterator<Item = Self::CopyType>

Returns an iterator over the T values in this array.

Source

fn iter_opt(&self) -> impl Iterator<Item = Option<Self::CopyType>>

Returns an iterator over the T values, as Option<Self::T>.

Source

fn iter_range( &self, offset: usize, len: usize, ) -> impl Iterator<Item = Self::CopyType>

Returns an iterator over a range of T values in this array.

Source

fn iter_opt_range( &self, offset: usize, len: usize, ) -> impl Iterator<Item = Option<Self::CopyType>>

Returns an iterator over a range of T values, as Option<T>.

Source

fn push(&mut self, value: Self::LogicalType)

Appends a value to the array, updating masks if present.

Source

unsafe fn push_unchecked(&mut self, value: Self::LogicalType)

Appends a value to the array, updating masks if present, without bounds checks.

§Safety

The caller must make sure there is enough pre-allocated size in the array, and no thread contention.

Source

fn slice_clone(&self, offset: usize, len: usize) -> Self

Returns a logical slice of the MaskedArraySelf::T [offset, offset+len) as a new MaskedArraySelf::T object via clone.

Prefer View trait slicers for zero-copy.

Source

fn resize(&mut self, n: usize, value: Self::LogicalType)

Resizes the array to contain n elements, via a call into self.data.resize().

If n is greater than the current length, new elements are added using T::default(). If n is smaller, the array is truncated. This only affects the data buffer, not the null mask.

Source

fn null_mask(&self) -> Option<&Bitmask>

We handle null masks consistently across all variants and thus their implementation sits on the trait, other than trait methods that need to access data state.

Returns a reference to the optional null mask.

Source

fn null_mask_mut(&mut self) -> Option<&mut Bitmask>

Returns a mutable reference to the optional null mask.

Source

fn set_null_mask(&mut self, mask: Option<Bitmask>)

Sets the null mask.

Source

fn append_array(&mut self, other: &Self)

Appends all values (and null mask if present) from other to self.

The appended array must be of the same concrete type and element type.

If this array is wrapped in a FieldArray, it will not be possible to mutate the array without reconstructing first, and a ChunkedArray is an alternative option.

Source

fn append_range( &mut self, other: &Self, offset: usize, len: usize, ) -> Result<(), MinarrowError>

Appends rows [offset..offset+len) from another array into self.

Like append_array but for a sub-range. Data and null masks are extended from the source range. The destination grows via its backing allocator.

Source

fn insert_rows( &mut self, index: usize, other: &Self, ) -> Result<(), MinarrowError>

Inserts all values (and null mask if present) from other into self at the specified index.

The inserted array must be of the same concrete type and element type. Elements at and after index are shifted to make room for the inserted values.

§Performance

This is an O(n) operation, where n is the number of elements that need to be shifted. For appending to the end, prefer append_array which is more efficient.

§Arguments

index - Position before which to insert (0 = prepend, self.len() = append)
other - Array to insert

§Errors

Returns an error if:

index > self.len() (out of bounds)
Type mismatch between self and other (for enum variants)

§Example

let mut arr = IntegerArray::from(vec![1, 2, 5, 6]);
let insert = IntegerArray::from(vec![3, 4]);
arr.insert_rows(2, &insert)?; // Now: [1, 2, 3, 4, 5, 6]

Source

fn split(self, index: usize) -> Result<(Self, Self), MinarrowError>
where Self: Sized,

Splits this array at the specified index, consuming self and returning two arrays.

The original array’s memory is split between the two resulting arrays without copying. The first array contains elements [0..index), the second contains [index..len).

§Arguments

index - Position to split at (0 < index < len)

§Errors

Returns an error if index == 0 or index >= len()

§Returns

A tuple of (before, after) where before contains [0..index) and after contains [index..len)

Source

fn extend_from_iter_with_capacity( &mut self, iter: I, additional_capacity: usize, )
where I: Iterator<Item = Self::LogicalType>,

Extends the array from an iterator with pre-allocated capacity.

Pre-allocates the specified additional capacity to avoid reallocations during bulk insertion, providing optimal performance for large datasets where the final size is known in advance.

Source

fn extend_from_slice(&mut self, slice: &[Self::LogicalType])

Extends the array from a slice of values.

More efficient than individual push operations as it pre-allocates capacity and can use bulk copy operations for compatible data types. For variable-length types like strings, calculates total byte requirements upfront.

Source

fn fill(value: Self::LogicalType, count: usize) -> Self

Creates a new array filled with the specified value repeated count times.

Pre-allocates exact capacity to avoid reallocations and uses efficient bulk operations where possible. For string types, calculates total byte requirements to minimise memory overhead.

Provided Methods§

Source

fn is_empty(&self) -> bool

Returns true if the array is empty.

Source

fn tuple_ref(&self, offset: usize, len: usize) -> (&Self, usize, usize)

Low-level accessor for when working directly with mutable array variants.

Borrows with window parameters as a tuple, for ‘DIY’ window access, retaining access to the whole original array.

Offset and Length are usize aliases.

For the standard zero-copy accessors, see the View trait.

Source

fn is_null(&self, idx: usize) -> bool

Returns true if the value at the given index is null.

Source

fn is_nullable(&self) -> bool

Checks if the array has a null bitmask.

Source

fn null_count(&self) -> usize

Returns the total number of nulls.

Source

fn push_null(&mut self)

Append a null value to the array, creating mask if needed

Source

unsafe fn push_null_unchecked(&mut self)

Appends a null value without any bounds‐checks on the mask.

§Safety

You must ensure that after push, the data and mask (if present) have capacity for the new index, or you risk OOB on either.

Source

fn set_null(&mut self, idx: usize)

Marks the value at the given index as null.

Source

unsafe fn set_null_unchecked(&mut self, idx: usize)

Like set_null, but skips bounds checks.

Source

fn push_nulls(&mut self, n: usize)

Bulk-extend this array with n null entries

Source

unsafe fn push_nulls_unchecked(&mut self, n: usize)

Bulk-extend this array with n null entries, using unchecked mask writes.

§Safety

Caller must ensure there are no data races across threads on this mask.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait MaskedArray Copy item path

§MaskedArray

§Purpose

Required Associated Types§

type T: Default + PartialEq + Clone + Copy

type Container

type LogicalType: Default

type CopyType: Default

Required Methods§

fn len(&self) -> usize

fn data(&self) -> &Self::Container

fn data_mut(&mut self) -> &mut Self::Container

fn get(&self, idx: usize) -> Option<Self::CopyType>

fn set(&mut self, idx: usize, value: Self::LogicalType)

unsafe fn get_unchecked(&self, idx: usize) -> Option<Self::CopyType>

unsafe fn set_unchecked(&mut self, idx: usize, value: Self::LogicalType)

fn iter(&self) -> impl Iterator<Item = Self::CopyType>

fn iter_opt(&self) -> impl Iterator<Item = Option<Self::CopyType>>

fn iter_range( &self, offset: usize, len: usize, ) -> impl Iterator<Item = Self::CopyType>

fn iter_opt_range( &self, offset: usize, len: usize, ) -> impl Iterator<Item = Option<Self::CopyType>>

fn push(&mut self, value: Self::LogicalType)

unsafe fn push_unchecked(&mut self, value: Self::LogicalType)

§Safety

fn slice_clone(&self, offset: usize, len: usize) -> Self

fn resize(&mut self, n: usize, value: Self::LogicalType)

fn null_mask(&self) -> Option<&Bitmask>

fn null_mask_mut(&mut self) -> Option<&mut Bitmask>

fn set_null_mask(&mut self, mask: Option<Bitmask>)

fn append_array(&mut self, other: &Self)

fn append_range( &mut self, other: &Self, offset: usize, len: usize, ) -> Result<(), MinarrowError>

fn insert_rows( &mut self, index: usize, other: &Self, ) -> Result<(), MinarrowError>

§Performance

§Arguments

§Errors

§Example

fn split(self, index: usize) -> Result<(Self, Self), MinarrowError>where Self: Sized,

§Arguments

§Errors

§Returns

fn extend_from_iter_with_capacity<I>( &mut self, iter: I, additional_capacity: usize, )where I: Iterator<Item = Self::LogicalType>,

fn extend_from_slice(&mut self, slice: &[Self::LogicalType])

fn fill(value: Self::LogicalType, count: usize) -> Self

Provided Methods§

fn is_empty(&self) -> bool

fn tuple_ref(&self, offset: usize, len: usize) -> (&Self, usize, usize)

fn is_null(&self, idx: usize) -> bool

fn is_nullable(&self) -> bool

fn null_count(&self) -> usize

fn push_null(&mut self)

unsafe fn push_null_unchecked(&mut self)

§Safety

fn set_null(&mut self, idx: usize)

unsafe fn set_null_unchecked(&mut self, idx: usize)

fn push_nulls(&mut self, n: usize)

unsafe fn push_nulls_unchecked(&mut self, n: usize)

§Safety

Dyn Compatibility§

Implementations on Foreign Types§

impl MaskedArray for Arc<BooleanArray<()>>

fn extend_from_iter_with_capacity<I>( &mut self, iter: I, additional_capacity: usize, )where I: Iterator<Item = <Arc<BooleanArray<()>> as MaskedArray>::LogicalType>,

fn extend_from_slice( &mut self, slice: &[<Arc<BooleanArray<()>> as MaskedArray>::LogicalType], )

fn fill( value: <Arc<BooleanArray<()>> as MaskedArray>::LogicalType, count: usize, ) -> Arc<BooleanArray<()>>

type T = bool

type Container = Bitmask

type LogicalType = bool

type CopyType = bool

fn len(&self) -> usize

fn is_empty(&self) -> bool

fn data(&self) -> &<Arc<BooleanArray<()>> as MaskedArray>::Container

fn data_mut(&mut self) -> &mut <Arc<BooleanArray<()>> as MaskedArray>::Container

fn get( &self, idx: usize, ) -> Option<<Arc<BooleanArray<()>> as MaskedArray>::CopyType>

fn set( &mut self, idx: usize, value: <Arc<BooleanArray<()>> as MaskedArray>::LogicalType, )

unsafe fn get_unchecked( &self, idx: usize, ) -> Option<<Arc<BooleanArray<()>> as MaskedArray>::CopyType>

unsafe fn set_unchecked( &mut self, idx: usize, value: <Arc<BooleanArray<()>> as MaskedArray>::LogicalType, )

fn iter( &self, ) -> impl Iterator<Item = <Arc<BooleanArray<()>> as MaskedArray>::CopyType>

fn iter_opt( &self, ) -> impl Iterator<Item = Option<<Arc<BooleanArray<()>> as MaskedArray>::CopyType>>

fn iter_range( &self, offset: usize, len: usize, ) -> impl Iterator<Item = <Arc<BooleanArray<()>> as MaskedArray>::CopyType>

fn iter_opt_range( &self, offset: usize, len: usize, ) -> impl Iterator<Item = Option<<Arc<BooleanArray<()>> as MaskedArray>::CopyType>>

fn push(&mut self, value: <Arc<BooleanArray<()>> as MaskedArray>::LogicalType)

unsafe fn push_unchecked( &mut self, value: <Arc<BooleanArray<()>> as MaskedArray>::LogicalType, )

Trait MaskedArray

fn split(self, index: usize) -> Result<(Self, Self), MinarrowError>
where Self: Sized,

fn extend_from_iter_with_capacity<I>( &mut self, iter: I, additional_capacity: usize, )
where I: Iterator<Item = Self::LogicalType>,

fn extend_from_iter_with_capacity<I>( &mut self, iter: I, additional_capacity: usize, )
where I: Iterator<Item = <Arc<BooleanArray<()>> as MaskedArray>::LogicalType>,

impl<T> MaskedArray for Arc<CategoricalArray<T>>
where T: Integer,

fn extend_from_iter_with_capacity<I>( &mut self, iter: I, additional_capacity: usize, )
where I: Iterator<Item = <Arc<CategoricalArray<T>> as MaskedArray>::LogicalType>,

impl<T> MaskedArray for Arc<DatetimeArray<T>>
where T: Integer,

fn extend_from_iter_with_capacity<I>( &mut self, iter: I, additional_capacity: usize, )
where I: Iterator<Item = <Arc<DatetimeArray<T>> as MaskedArray>::LogicalType>,