Struct arrow_array::builder::GenericListBuilder

pub struct GenericListBuilder<OffsetSize: OffsetSizeTrait, T: ArrayBuilder> { /* private fields */ }

Builder for GenericListArray

Use ListBuilder to build ListArrays and LargeListBuilder to build LargeListArrays.

Example

Here is code that constructs a ListArray with the contents: [[A,B,C], [], NULL, [D], [NULL, F]]

let values_builder = StringBuilder::new();
let mut builder = ListBuilder::new(values_builder);

// [A, B, C]
builder.values().append_value("A");
builder.values().append_value("B");
builder.values().append_value("C");
builder.append(true);

// [ ] (empty list)
builder.append(true);

// Null
builder.values().append_value("?"); // irrelevant
builder.append(false);

// [D]
builder.values().append_value("D");
builder.append(true);

// [NULL, F]
builder.values().append_null();
builder.values().append_value("F");
builder.append(true);

// Build the array
let array = builder.finish();

// Values is a string array
// "A", "B" "C", "?", "D", NULL, "F"
assert_eq!(
  array.values().as_ref(),
  &StringArray::from(vec![
    Some("A"), Some("B"), Some("C"),
    Some("?"), Some("D"), None,
    Some("F")
  ])
);

// Offsets are indexes into the values array
assert_eq!(
  array.value_offsets(),
  &[0, 3, 3, 4, 5, 7]
);

Implementations

impl<OffsetSize: OffsetSizeTrait, T: ArrayBuilder> GenericListBuilder<OffsetSize, T>

pub fn new(values_builder: T) -> Self

Creates a new GenericListBuilder from a given values array builder

pub fn with_capacity(values_builder: T, capacity: usize) -> Self

Creates a new GenericListBuilder from a given values array builder capacity is the number of items to pre-allocate space for in this builder

pub fn with_field(self, field: impl Into<FieldRef>) -> Self

Override the field passed to GenericListArray::new

By default a nullable field is created with the name item

Note: Self::finish and Self::finish_cloned will panic if the field’s data type does not match that of T

impl<OffsetSize: OffsetSizeTrait, T> GenericListBuilder<OffsetSize, T>

where T: 'static + ArrayBuilder,

pub fn values(&mut self) -> &mut T

Returns the child array builder as a mutable reference.

This mutable reference can be used to append values into the child array builder, but you must call append to delimit each distinct list value.

pub fn values_ref(&self) -> &T

Returns the child array builder as an immutable reference

pub fn append(&mut self, is_valid: bool)

Finish the current variable-length list array slot

Panics

Panics if the length of Self::values exceeds OffsetSize::MAX

pub fn append_value<I, V>(&mut self, i: I)

where T: Extend<Option<V>>, I: IntoIterator<Item = Option<V>>,

Append a value to this GenericListBuilder

let mut builder = ListBuilder::new(Int32Builder::new());

builder.append_value([Some(1), Some(2), Some(3)]);
builder.append_value([]);
builder.append_value([None]);

let array = builder.finish();
assert_eq!(array.len(), 3);

assert_eq!(array.value_offsets(), &[0, 3, 3, 4]);
let values = array.values().as_primitive::<Int32Type>();
assert_eq!(values, &Int32Array::from(vec![Some(1), Some(2), Some(3), None]));

This is an alternative API to appending directly to Self::values and delimiting the result with Self::append

let mut builder = ListBuilder::new(Int32Builder::new());

builder.values().append_value(1);
builder.values().append_value(2);
builder.values().append_value(3);
builder.append(true);
builder.append(true);
builder.values().append_null();
builder.append(true);

let array = builder.finish();
assert_eq!(array.len(), 3);

assert_eq!(array.value_offsets(), &[0, 3, 3, 4]);
let values = array.values().as_primitive::<Int32Type>();
assert_eq!(values, &Int32Array::from(vec![Some(1), Some(2), Some(3), None]));

pub fn append_null(&mut self)

Append a null to this GenericListBuilder

See Self::append_value for an example use.

pub fn append_option<I, V>(&mut self, i: Option<I>)

where T: Extend<Option<V>>, I: IntoIterator<Item = Option<V>>,

Appends an optional value into this GenericListBuilder

If Some calls Self::append_value otherwise calls Self::append_null

pub fn finish(&mut self) -> GenericListArray<OffsetSize>

Builds the GenericListArray and reset this builder.

pub fn finish_cloned(&self) -> GenericListArray<OffsetSize>

Builds the GenericListArray without resetting the builder.

pub fn offsets_slice(&self) -> &[OffsetSize]

Returns the current offsets buffer as a slice

pub fn validity_slice(&self) -> Option<&[u8]>

Returns the current null buffer as a slice

Trait Implementations

impl<OffsetSize: OffsetSizeTrait, T> ArrayBuilder for GenericListBuilder<OffsetSize, T>

where T: 'static + ArrayBuilder,

fn as_any(&self) -> &dyn Any

Returns the builder as a non-mutable Any reference.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the builder as a mutable Any reference.

fn into_box_any(self: Box<Self>) -> Box<dyn Any>

Returns the boxed builder as a box of Any.

fn len(&self) -> usize

Returns the number of array slots in the builder

fn finish(&mut self) -> ArrayRef

Builds the array and reset this builder.

fn finish_cloned(&self) -> ArrayRef

Builds the array without resetting the builder.

fn is_empty(&self) -> bool

Returns whether number of array slots is zero

impl<OffsetSize: Debug + OffsetSizeTrait, T: Debug + ArrayBuilder> Debug for GenericListBuilder<OffsetSize, T>

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

Formats the value using the given formatter.

impl<O: OffsetSizeTrait, T: ArrayBuilder + Default> Default for GenericListBuilder<O, T>

fn default() -> Self

Returns the “default value” for a type.

impl<O, B, V, E> Extend<Option<V>> for GenericListBuilder<O, B>

where O: OffsetSizeTrait, B: ArrayBuilder + Extend<E>, V: IntoIterator<Item = E>,

fn extend<T: IntoIterator<Item = Option<V>>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.