Struct ListData 

pub struct ListData;

A list array that stores variable-length lists of elements, similar to Vec<Vec<T>>.

This mirrors the Apache Arrow List array encoding and provides efficient storage for nested data where each row contains a list of elements of the same type.

Data Layout

The list array uses an offset-based encoding:

• Elements array: A flat array containing all list elements concatenated together
• Offsets array: Integer array where offsets[i] is an (inclusive) start index into the elements and offsets[i+1] is the (exclusive) stop index for the ith list.
• Validity: Optional mask indicating which lists are null

This allows for excellent cascading compression of the elements and offsets, as similar values are clustered together and the offsets have a predictable pattern and small deltas between consecutive elements.

Offset Semantics

• Offsets must be non-nullable integers (i32, i64, etc.)
• Offsets array has length n+1 where n is the number of lists
• List i contains elements from elements[offsets[i]..offsets[i+1]]
• Offsets must be monotonically increasing

Examples

use vortex_array::arrays::{ListArray, PrimitiveArray};
use vortex_array::arrays::list::ListArrayExt;
use vortex_array::validity::Validity;
use vortex_array::IntoArray;
use vortex_buffer::buffer;
use std::sync::Arc;

// Create a list array representing [[1, 2], [3, 4, 5], []]
let elements = buffer![1i32, 2, 3, 4, 5].into_array();
let offsets = buffer![0u32, 2, 5, 5].into_array(); // 3 lists

let list_array = ListArray::try_new(
    elements.into_array(),
    offsets.into_array(),
    Validity::NonNullable,
).unwrap();

assert_eq!(list_array.len(), 3);

// Access individual lists
let first_list = list_array.list_elements_at(0).unwrap();
assert_eq!(first_list.len(), 2); // [1, 2]

let third_list = list_array.list_elements_at(2).unwrap();
assert!(third_list.is_empty()); // []

Implementations

impl ListData

pub fn build(elements: ArrayRef, offsets: ArrayRef, validity: Validity) -> Self

Creates a new ListArray.

Panics

Panics if the provided components do not satisfy the invariants documented in ListArray::new_unchecked.

pub unsafe fn new_unchecked() -> Self

Creates a new ListArray without validation from these components:

• elements is a flat array containing all list elements concatenated.
• offsets is an integer array where offsets[i] is the start index for list i.
• validity holds the null values.

Safety

The caller must ensure all of the following invariants are satisfied:

• Offsets must be a non-nullable integer array.
• Offsets must have at least one element (even for empty lists, it should contain [0]).
• Offsets must be sorted (monotonically increasing).
• All offset values must be non-negative.
• The maximum offset must not exceed elements.len().
• If validity is an array, its length must equal offsets.len() - 1.

pub fn validate( elements: &ArrayRef, offsets: &ArrayRef, validity: &Validity, ) -> VortexResult<()>

Validates the components that would be used to create a ListArray.

This function checks all the invariants required by ListArray::new_unchecked.

Trait Implementations

impl ArrayEq for ListData

fn array_eq(&self, _other: &Self, _precision: Precision) -> bool

impl ArrayHash for ListData

fn array_hash<H: Hasher>(&self, _state: &mut H, _precision: Precision)

impl Clone for ListData

fn clone(&self) -> ListData

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ListData

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

Formats the value using the given formatter.

impl Default for ListData

fn default() -> ListData

Returns the “default value” for a type.

impl Display for ListData

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

Formats the value using the given formatter.