Struct arrow_array::builder::GenericListBuilder

source ·

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

Expand description

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§

source §

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

source

pub fn new(values_builder: T) -> Self

Creates a new GenericListBuilder from a given values array builder

source

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

source §

impl<OffsetSize: OffsetSizeTrait, T> GenericListBuilder<OffsetSize, T>where T: 'static + ArrayBuilder,

source

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.

source

pub fn values_ref(&self) -> &T

Returns the child array builder as an immutable reference

source

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

source

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]));