Struct FieldArray 

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

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

impl FieldArray

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

Constructs a new FieldArray from an existing Field and Array.

Examples found in repository

examples/pycapsule_exchange.rs (lines 166-169)

fn example_2_export_table_stream(py: Python<'_>) -> PyResult<()> {
    println!("Example 2: Export MinArrow table -> PyArrow via __arrow_c_stream__");
    println!("------------------------------------------------------------------");

    let mut ids = IntegerArray::<i32>::default();
    ids.push(1);
    ids.push(2);
    ids.push(3);

    let mut scores = FloatArray::<f64>::default();
    scores.push(9.5);
    scores.push(8.3);
    scores.push(7.1);

    let table = Table::new(
        "results".to_string(),
        Some(vec![
            FieldArray::new(
                Field::new("id", ArrowType::Int32, false, None),
                Array::from_int32(ids),
            ),
            FieldArray::new(
                Field::new("score", ArrowType::Float64, false, None),
                Array::from_float64(scores),
            ),
        ]),
    );
    println!("  Created MinArrow table: 3 rows x 2 columns (id, score)");

    // Export as a stream capsule and extract the raw pointer for PyArrow
    let stream_capsule = to_py::table_to_stream_capsule(&table, py)?;
    let stream_ptr = unsafe {
        pyo3::ffi::PyCapsule_GetPointer(
            stream_capsule.as_ptr(),
            c"arrow_array_stream".as_ptr(),
        )
    } as usize;

    let pyarrow = py.import("pyarrow")?;
    let reader = pyarrow
        .getattr("RecordBatchReader")?
        .call_method1("_import_from_c", (stream_ptr,))?;
    let pa_table = reader.call_method0("read_all")?;

    let num_rows: usize = pa_table.getattr("num_rows")?.extract()?;
    let schema_repr: String = pa_table.getattr("schema")?.call_method0("__repr__")?.extract()?;
    println!("  PyArrow received: {} rows", num_rows);
    println!("  Schema: {}", schema_repr.lines().next().unwrap_or(""));
    println!("  Done.\n");
    Ok(())
}

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

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

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.

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.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn arrow_type(&self) -> ArrowType

pub fn tz(&self, tz: &str) -> Result<FieldArray, MinarrowError>

Returns a new FieldArray with updated timezone metadata.

The underlying timestamp data (always UTC) remains unchanged. Only the timezone metadata in the Field’s ArrowType is updated for interpretation/display purposes.

Arguments

• tz - Timezone string in Arrow format (IANA like “America/New_York” or offset like “+05:00”)

Errors

Returns an error if the array is not a Timestamp type.

pub fn utc(&self) -> Result<FieldArray, MinarrowError>

Returns a new FieldArray with timezone metadata set to “UTC”.

The underlying timestamp data (always UTC) remains unchanged. Only the timezone metadata in the Field’s ArrowType is updated.

Errors

Returns an error if the array is not a Timestamp type.

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.

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

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

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.

pub fn null_count(&self) -> usize

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

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.

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.

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.

Trait Implementations

impl Clone for FieldArray

fn clone(&self) -> FieldArray

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Concatenate for FieldArray

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

Concatenates two FieldArrays, consuming both.

Requirements

• Both FieldArrays must have matching field metadata:
  • Same name
  • Same dtype
  • Same nullability

Returns

A new FieldArray with the concatenated array data

Errors

• IncompatibleTypeError if field metadata doesn’t match

impl Debug for FieldArray

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

Formats the value using the given formatter.

impl Display for FieldArray

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

Formats the value using the given formatter.

impl From<FieldArray> for PyArray

fn from(field_array: FieldArray) -> Self

Converts to this type from the input type.

impl From<FieldArray> for SuperArray

fn from(fa: FieldArray) -> SuperArray

Converts to this type from the input type.

impl From<PyArray> for FieldArray

fn from(value: PyArray) -> Self

Converts to this type from the input type.

impl FromIterator<FieldArray> for SuperArray

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

where T: IntoIterator<Item = FieldArray>,

Creates a value from an iterator.

impl PartialEq for FieldArray

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RowSelection for FieldArray

Available on crate features select and views only.

type View = ArrayV

The view type returned by selection operations

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

where S: DataSelector,

Select rows by index or range

fn get_row_count(&self) -> usize

Get the count for data resolution

impl Shape for FieldArray

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 FieldArray