Enum Array 

#[repr(C, align(64))]
pub enum Array {
    NumericArray(NumericArray),
    TextArray(TextArray),
    BooleanArray(Arc<BooleanArray<()>>),
    Null,
}

Array

Standard Array type. Wrap in a FieldArray when using inside a Table or as a standalone value requiring tagged metadata.

Overview

The dual-enum approach may look verbose but works well in practice:

• Enables clean function signatures with direct access to concrete types (e.g. &NumericArray), supporting trait-aligned dispatch without exhaustive matches at every call site.
• Supports ergonomic categorisation: functions typically match on the outer enum for broad category handling (numeric, text, temporal, boolean), while allowing inner variant matching for precise type handling.
• The focused typeset (no nested types) helps keeps enum size efficient as memory is allocated for the largest variant.

Usage

Functions can accept references tailored to the intended match granularity:

• &IntegerArray: direct reference to the inner type e.g., arr.num().i64().
• &NumericArray: any numeric type via arr.num().
• &Array: match on categories or individual types.

Benefits

• No heap allocation or runtime indirection - all enum variants are inline with minimal discriminant cost.
• Unified call sites with compiler-enforced type safety.
• Easy casting to inner types (e.g., .str() for strings).
• Supports aggressive compiler inlining, unlike approaches relying on dynamic dispatch and downcasting.

Trade-offs

• Adds ~30–100 ns latency compared to direct inner type calls - only noticeable in extreme low-latency contexts such as HFT.
• Requires enum matching at dispatch sites compared to direct inner type usage.

Examples

use minarrow::{
    Array, IntegerArray, NumericArray, arr_bool, arr_f64, arr_i32, arr_i64,
    arr_str32, vec64
};

// Fast macro construction
let int_arr = arr_i32![1, 2, 3, 4];
let float_arr = arr_f64![0.5, 1.5, 2.5];
let bool_arr = arr_bool![true, false, true];
let str_arr = arr_str32!["a", "b", "c"];

assert_eq!(int_arr.len(), 4);
assert_eq!(str_arr.len(), 3);

// Manual construction
let int = IntegerArray::<i64>::from_slice(&[100, 200]);
let wrapped: NumericArray = NumericArray::Int64(std::sync::Arc::new(int));
let array = Array::NumericArray(wrapped);

Variants

NumericArray(NumericArray)

TextArray(TextArray)

BooleanArray(Arc<BooleanArray<()>>)

Null

Implementations

impl Array

pub fn from_int32(arr: IntegerArray<i32>) -> Array

Creates an Array enum with an Int32 array.

pub fn from_int64(arr: IntegerArray<i64>) -> Array

Creates an Array enum with an Int64 array.

pub fn from_uint32(arr: IntegerArray<u32>) -> Array

Creates an Array enum with a UInt32 array.

pub fn from_uint64(arr: IntegerArray<u64>) -> Array

Creates an Array enum with an UInt64 array.

pub fn from_float32(arr: FloatArray<f32>) -> Array

Creates an Array enum with a Float32 array.

pub fn from_float64(arr: FloatArray<f64>) -> Array

Creates an Array enum with a Float64 array.

pub fn from_string32(arr: StringArray<u32>) -> Array

Creates an Array enum with a String32 array.

pub fn from_string64(arr: StringArray<u64>) -> Array

Creates an Array enum with a String64 array.

pub fn from_categorical8(arr: CategoricalArray<u8>) -> Array

Creates an Array enum with a Categorical8 array.

pub fn from_bool(arr: BooleanArray<()>) -> Array

Creates an Array enum with a Boolean array.

pub fn fa(self, name: impl Into<String>) -> FieldArray

Wraps this Array in a FieldArray with the given name.

Infers the Arrow type and nullability from the array itself.

Example

use minarrow::{Array, IntegerArray, MaskedArray};

let mut arr = IntegerArray::<i32>::default();
arr.push(1);
arr.push(2);
let array = Array::from_int32(arr);
let field_array = array.fa("my_column");
assert_eq!(field_array.field.name, "my_column");

pub fn num_ref(&self) -> Result<&NumericArray, MinarrowError>

Returns a reference to the inner NumericArray if the variant matches. No conversion or cloning is performed.

pub fn str_ref(&self) -> Result<&TextArray, MinarrowError>

Returns a reference to the inner TextArray if the variant matches. No conversion or cloning is performed.

pub fn bool_ref(&self) -> Result<&BooleanArray<()>, MinarrowError>

Returns a reference to the inner BooleanArray if the variant matches. No conversion or cloning is performed.

pub fn try_i32_ref(&self) -> Result<&IntegerArray<i32>, MinarrowError>

Returns a reference to the inner IntegerArray<i32>.

pub fn try_i64_ref(&self) -> Result<&IntegerArray<i64>, MinarrowError>

Returns a reference to the inner IntegerArray<i64>.

pub fn try_u32_ref(&self) -> Result<&IntegerArray<u32>, MinarrowError>

Returns a reference to the inner IntegerArray<u32>.

pub fn try_u64_ref(&self) -> Result<&IntegerArray<u64>, MinarrowError>

Returns a reference to the inner IntegerArray<u64>.

pub fn try_f32_ref(&self) -> Result<&FloatArray<f32>, MinarrowError>

Returns a reference to the inner FloatArray<f32>.

pub fn try_f64_ref(&self) -> Result<&FloatArray<f64>, MinarrowError>

Returns a reference to the inner FloatArray<f64>.

pub fn try_str32_ref(&self) -> Result<&StringArray<u32>, MinarrowError>

Returns a reference to the inner StringArray<u32>.

pub fn try_str64_ref(&self) -> Result<&StringArray<u64>, MinarrowError>

Returns a reference to the inner StringArray<u64>.

pub fn try_cat8_ref(&self) -> Result<&CategoricalArray<u8>, MinarrowError>

Returns a reference to the inner CategoricalArray<u8>.

pub fn num(self) -> NumericArray

Returns an inner NumericArray, consuming self.

• If already a NumericArray, consumes and returns the inner value with no clone.
• Other types: casts and copies.

pub fn str(self) -> TextArray

Returns an inner TextArray, consuming self.

• If already a TextArray, consumes and returns the inner value with no clone.
• Other types: casts (to string) and copies.

pub fn bool(self) -> Arc<BooleanArray<()>>

Returns the inner BooleanArray, consuming self.

• If already a BooleanArray, consumes and returns the inner value with no clone.
• Other types: calculates the boolean mask based on whether the value is present, and non-zero, and copies. In these cases, any null mask is preserved, rather than becoming false.

pub fn len(&self) -> usize

Returns the length of the array.

pub fn view(&self, offset: usize, len: usize) -> ArrayV

Returns a metadata view and reference over the specified window of this array.

Does not slice the object (yet).

Panics if out of bounds.

pub fn view_tuple(&self, offset: usize, len: usize) -> (&Array, usize, usize)

Returns a metadata view and reference over the specified window of this array.

Does not slice the object (yet).

Panics if out of bounds.

pub fn inner<T>(&self) -> &Arc<T>

where T: 'static,

Returns a reference to the inner array as type Arc<T>.

This is compile-time safe if T matches the actual payload, but will panic otherwise. Prefer .inner_check() for Option-based pattern.

pub fn inner_mut<T>(&mut self) -> &mut Arc<T>

where T: 'static,

Returns a mutable reference to the inner array as type T.

This method is compile-time safe when the type T matches the actual inner type, but relies on TypeId checks and unsafe casting. If an incorrect type is specified, this will panic at runtime.

Prefer inner_check_mut if you want an Option-based version that avoids panics.

pub fn inner_check<T>(&self) -> Option<&Arc<T>>

where T: 'static,

Returns a reference to the inner array as type T, if the type matches.

This method performs a runtime TypeId check to verify that the provided type T corresponds to the actual inner variant. If the types match, returns Some(&T); otherwise, returns None without panicking.

Use when the type of the variant is uncertain at compile time.

pub fn inner_check_mut<T>(&mut self) -> Option<&mut Arc<T>>

where T: 'static,

Returns a mutable reference to the inner array as type T, if the type matches.

This method performs a runtime TypeId check to verify that the provided type T corresponds to the actual inner variant. If the types match, returns Some(&mut T); otherwise, returns None without panicking.

Use when the type of the variant is uncertain at compile time.

pub fn as_slice<T>(&self, offset: usize, len: usize) -> &[T]

pub fn slice_raw<T>(&self, offset: usize, len: usize) -> Option<&[T]>

where T: 'static,

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

Returns a new Array of the same variant sliced to the given offset and length . Copies the data of the scoped range that’s selected.

If out-of-bounds, returns Self::Null. All null mask, offsets, etc. are trimmed.

pub fn arrow_type(&self) -> ArrowType

Arrow physical type for this array.

pub fn is_nullable(&self) -> bool

Column nullability

pub fn is_categorical_array(&self) -> bool

Returns true if this is a categorical array.

pub fn is_string_array(&self) -> bool

Returns true if this is a string array i.e. non-categorical text.

pub fn is_text_array(&self) -> bool

Returns true if this is any text array, string or categorical.

pub fn is_boolean_array(&self) -> bool

Returns true if this is a boolean array.

pub fn is_integer_array(&self) -> bool

Returns true if this is an integer array.

pub fn is_float_array(&self) -> bool

Returns true if this is a floating-point array.

pub fn is_numerical_array(&self) -> bool

Returns true if this is any numeric array, integer or float.

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

Returns the underlying null mask of the array

pub fn value_to_string(&self, idx: usize) -> String

Format the element at idx as a human-readable string.

Returns "null" for null elements. Uses the same formatting as the array’s Display implementation.

pub fn null_array(arrow_type: &ArrowType, n_rows: usize) -> Array

Create an all-null array of the given ArrowType with n_rows elements.

The data buffer is zero-filled and every element is masked as null. For datetime types, set the time_unit on the returned array afterwards.

pub fn compare_at(&self, i: usize, j: usize) -> Ordering

Compare two elements within the same array by index.

Uses total ordering for floats via total_cmp(). Nulls sort last: null > any value, null == null.

pub fn set_null_mask(&mut self, mask: Bitmask)

Set null mask on Array by matching on variants

pub fn data_ptr_and_byte_len(&self) -> (*const u8, usize, usize)

Returns a pointer to the backing data (contiguous bytes), length in elements, and element size.

This is not logical length - it is total raw bytes in the buffer, so for non-fixed width types such as bit-packed booleans or strings, please factor this in accordingly.

pub fn null_mask_ptr_and_byte_len(&self) -> Option<(*const u8, usize)>

Returns a pointer to the null mask and its length in bytes, if present.

pub fn offsets_ptr_and_len(&self) -> Option<(*const u8, usize)>

Offsets pointer/len for variable-length types

pub fn null_count(&self) -> usize

Returns the null count of the array

pub fn concat_array(&mut self, other: &Array)

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

Panics if the two arrays are of different variants or incompatible types.

This function uses copy-on-write semantics for arrays wrapped in Arc. If self is the only owner of its data, appends are performed in place without copying the first array. If the array data is shared (Arc reference count > 1), the data is first cloned (so the mutation does not affect other owners), and the append is then performed on the unique copy. The second array is allocated into the buffer, which is standard.

pub fn concat_array_range( &mut self, other: &Array, offset: usize, len: usize, ) -> Result<(), MinarrowError>

Appends rows [offset..offset+len) from another array into self. Extends data and null masks directly from the source range.

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

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

This is an O(n) operation.

Returns an error if the two arrays are of different variants or incompatible types, or if the index is out of bounds.

pub fn split( self, index: usize, field: &Arc<Field>, ) -> Result<SuperArray, MinarrowError>

Splits the Array at the specified index, consuming self and returning a SuperArray with two FieldArray chunks.

Splits the underlying buffers (via vec .split_off()), allocating new storage for the second half. More efficient than cloning the entire array but requires allocation.

Trait Implementations

impl Clone for Array

fn clone(&self) -> Array

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Concatenate for Array

fn concat(self, other: Array) -> Result<Array, MinarrowError>

Concatenates self with other, consuming both and returning a new instance.

impl Debug for Array

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Array

fn default() -> Array

Returns the “default value” for a type.

impl Display for Array

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<Arc<BooleanArray<()>>> for Array

fn from(a: Arc<BooleanArray<()>>) -> Array

Converts to this type from the input type.

impl From<Arc<CategoricalArray<u8>>> for Array

Available on crate feature default_categorical_8 only.

fn from(a: Arc<CategoricalArray<u8>>) -> Array

Converts to this type from the input type.

impl From<Arc<FloatArray<f32>>> for Array

fn from(a: Arc<FloatArray<f32>>) -> Array

Converts to this type from the input type.

impl From<Arc<FloatArray<f64>>> for Array

fn from(a: Arc<FloatArray<f64>>) -> Array

Converts to this type from the input type.

impl From<Arc<IntegerArray<i32>>> for Array

fn from(a: Arc<IntegerArray<i32>>) -> Array

Converts to this type from the input type.

impl From<Arc<IntegerArray<i64>>> for Array

fn from(a: Arc<IntegerArray<i64>>) -> Array

Converts to this type from the input type.

impl From<Arc<IntegerArray<u32>>> for Array

fn from(a: Arc<IntegerArray<u32>>) -> Array

Converts to this type from the input type.

impl From<Arc<IntegerArray<u64>>> for Array

fn from(a: Arc<IntegerArray<u64>>) -> Array

Converts to this type from the input type.

impl From<Arc<StringArray<u32>>> for Array

fn from(a: Arc<StringArray<u32>>) -> Array

Converts to this type from the input type.

impl From<Arc<StringArray<u64>>> for Array

Available on crate feature large_string only.

fn from(a: Arc<StringArray<u64>>) -> Array

Converts to this type from the input type.

impl From<Array> for SuperArray

fn from(array: Array) -> SuperArray

Converts to this type from the input type.

impl From<Array> for BooleanArrayV

fn from(array: Array) -> BooleanArrayV

Converts to this type from the input type.

impl From<Array> for NumericArrayV

fn from(array: Array) -> NumericArrayV

Converts to this type from the input type.

impl From<Array> for TextArrayV

fn from(array: Array) -> TextArrayV

Converts to this type from the input type.

impl From<Array> for ArrayV

Array -> ArrayView

Uses Offset 0 and length self.len()

fn from(array: Array) -> ArrayV

Converts to this type from the input type.

impl From<BooleanArray<()>> for Array

fn from(a: BooleanArray<()>) -> Array

Converts to this type from the input type.

impl From<CategoricalArray<u8>> for Array

Available on crate feature default_categorical_8 only.

fn from(a: CategoricalArray<u8>) -> Array

Converts to this type from the input type.

impl From<FloatArray<f32>> for Array

fn from(a: FloatArray<f32>) -> Array

Converts to this type from the input type.

impl From<FloatArray<f64>> for Array

fn from(a: FloatArray<f64>) -> Array

Converts to this type from the input type.

impl From<IntegerArray<i32>> for Array

fn from(a: IntegerArray<i32>) -> Array

Converts to this type from the input type.

impl From<IntegerArray<i64>> for Array

fn from(a: IntegerArray<i64>) -> Array

Converts to this type from the input type.

impl From<IntegerArray<u32>> for Array

fn from(a: IntegerArray<u32>) -> Array

Converts to this type from the input type.

impl From<IntegerArray<u64>> for Array

fn from(a: IntegerArray<u64>) -> Array

Converts to this type from the input type.

impl From<StringArray<u32>> for Array

fn from(a: StringArray<u32>) -> Array

Converts to this type from the input type.

impl From<StringArray<u64>> for Array

Available on crate feature large_string only.

fn from(a: StringArray<u64>) -> Array

Converts to this type from the input type.

impl From<Vec64<f32>> for Array

fn from(vec: Vec64<f32>) -> Array

Converts to this type from the input type.

impl From<Vec64<f64>> for Array

fn from(vec: Vec64<f64>) -> Array

Converts to this type from the input type.

impl From<Vec64<i32>> for Array

fn from(vec: Vec64<i32>) -> Array

Converts to this type from the input type.

impl From<Vec64<i64>> for Array

fn from(vec: Vec64<i64>) -> Array

Converts to this type from the input type.

impl From<Vec64<u32>> for Array

fn from(vec: Vec64<u32>) -> Array

Converts to this type from the input type.

impl From<Vec64<u64>> for Array

fn from(vec: Vec64<u64>) -> Array

Converts to this type from the input type.

impl FromIterator<Array> for SuperArray

fn from_iter<T>(iter: T) -> SuperArray

where T: IntoIterator<Item = Array>,

Creates a value from an iterator.

impl PartialEq for Array

fn eq(&self, other: &Array) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl RowSelection for Array

Available on crate features select and views only.

fn r<S>(&self, selection: S) -> ArrayV

where S: DataSelector,

Select rows by index or range, returning an ArrayV (view)

For contiguous selections (ranges), creates a zero-copy view. For non-contiguous selections (index arrays), gathers into a new array.

type View = ArrayV

The view type returned by selection operations

fn get_row_count(&self) -> usize

Get the count for data resolution

impl Shape for Array

fn shape(&self) -> ShapeDim

Returns arbitrary Shape dimension for any data shape

fn shape_1d(&self) -> usize

Returns the first dimension shape

fn shape_2d(&self) -> (usize, usize)

Returns the first and second dimension shapes

fn shape_3d(&self) -> (usize, usize, usize)

Returns the first, second and third dimension shapes

fn shape_4d(&self) -> (usize, usize, usize, usize)

Returns the first, second, third and fourth dimension shapes

impl StructuralPartialEq for Array