Struct FieldArray

Source

pub struct FieldArray {
    pub field: Arc<Field>,
    pub array: Array,
    pub null_count: usize,
}

Expand description

§FieldArray

Named and typed data column with associated array values.

§Role

Combines a Field with an immutable Array instance.
FieldArray integrates naturally into a Table, where immutability enforces row-length guarantees. It can also serve as a self-documenting array and is required when sending Minarrow data over FFI to Apache Arrow. In such cases, it’s worth ensuring the correct logical Datetime Arrow type is built when constructing the Field, as this determines the Arrow type on the receiving side.

§Examples

use minarrow::{Array, Field, FieldArray, MaskedArray};
use minarrow::ffi::arrow_dtype::ArrowType;
use minarrow::structs::variants::integer::IntegerArray;

// Build a typed array
let mut ints = IntegerArray::<i32>::default();
ints.push(1);
ints.push(2);
let arr = Array::from_int32(ints);

// Construct with a Field and Array
let field = Field::new("id", ArrowType::Int32, false, None);
let fa = FieldArray::new(field, arr);

assert_eq!(fa.field.name, "id");
assert_eq!(fa.arrow_type(), ArrowType::Int32);
assert_eq!(fa.len(), 2);

// Take an owned slice [offset..offset+len)
let sub = fa.slice_clone(0, 1);
assert_eq!(sub.len(), 1);

The fa_* macros are a concise construction shorthand:

use minarrow::{fa_i32, fa_i32_opt, fa_str32};
use minarrow::ffi::arrow_dtype::ArrowType;

// From literal values - type and nullability inferred
let fa = fa_i32!("id", 1, 2);
assert_eq!(fa.field.name, "id");
assert_eq!(fa.arrow_type(), ArrowType::Int32);
assert_eq!(fa.len(), 2);

// Nullable variant with Option values
let fa = fa_i32_opt!("score", Some(10i32), None::<i32>, Some(30));
assert_eq!(fa.len(), 3);
assert!(fa.field.nullable);
assert_eq!(fa.null_count(), 1);

// String columns
let names = fa_str32!("name", "alice", "bob");
assert_eq!(names.field.name, "name");
assert_eq!(names.len(), 2);

Fields§

§field: Arc<Field>

Array metadata

§array: Array

The array’s inner payload is wrapped in Arc for immutability so it can safely share across threads. When part of a Table (or higher-dimensional structure), immutability also upholds shape constraints.

§null_count: usize

Null count for the immutable array to support skipping null-mask operations when it’s 0, and/or related strategies.

Implementations§

Source §

impl FieldArray

Source

pub fn new(field: Field, array: Array) -> FieldArray

Constructs a new FieldArray from an existing Field and Array.

Source

pub fn new_arc(field: Arc<Field>, array: Array) -> FieldArray

Constructs a new FieldArray from an existing Arc<Field> and Array.

Source

pub fn from_arr<N, A>(name: N, arr: A) -> FieldArray
where N: Into<String>, A: Into<Array>,

Constructs a new FieldArray from a name and any supported typed array, automatically wrapping as Array and inferring type and nullability.

Source

pub fn from_parts<T>( field_name: T, dtype: ArrowType, nullable: Option<bool>, metadata: Option<BTreeMap<String, String>>, array: Array, ) -> FieldArray
where T: Into<String>,

Constructs a new FieldArray from raw field components and an Array.

Source

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

Returns a zero-copy view (FieldArraySlice) into the window [offset, offset+len).

The returned object holds references into the original FieldArray.

The (&Array, Offset, WindowLength), &Field) FieldArraySlice pattern here is a once-off we avoid recommending.

Source

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

Returns a new owned FieldArray with array sliced [offset, offset+len).

Source

pub fn refresh_null_count(&mut self)

Updates the cached null_count from the underlying array. Should be called after any mutation of the array that could change null count.

Source

pub fn null_count(&self) -> usize

Returns the cached null count. This is kept in sync with the underlying array via refresh_null_count().

Source

pub fn concat_field_array(&mut self, other: &FieldArray)

Concatenates another FieldArray’s data into this one using copy-on-write semantics. If this FieldArray’s array has Arc reference count > 1, the data is cloned first. Both FieldArrays must have compatible types. Updates the cached null_count.

Source

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

Appends rows [offset..offset+len) from another FieldArray into self. Extends data directly from the source’s backing buffer.

Source

pub fn with_array_mut<F, R>(&mut self, f: F) -> R
where F: FnOnce(&mut Array) -> R,

Provides mutable access to the underlying array with automatic null_count refresh. Uses copy-on-write semantics - clones array data if Arc reference count > 1. Use this for operations that may change the null count.