Struct VariantArrayBuilder 

pub struct VariantArrayBuilder {
    nulls: NullBufferBuilder,
    metadata_builder: WritableMetadataBuilder,
    metadata_offsets: Vec<usize>,
    value_builder: ValueBuilder,
    value_offsets: Vec<usize>,
    fields: Fields,
}

A builder for VariantArray

This builder is used to construct a VariantArray and allows APIs for adding metadata

This builder always creates a VariantArray using [BinaryViewArray] for both the metadata and value fields.

TODO

1. Support shredding: https://github.com/apache/arrow-rs/issues/7895

Example:

// Create a new VariantArrayBuilder with a capacity of 100 rows
let mut builder = VariantArrayBuilder::new(100);
// append variant values
builder.append_variant(Variant::from(42));
// append a null row (note not a Variant::Null)
builder.append_null();
// append an object to the builder using VariantBuilderExt methods directly
builder.new_object()
  .with_field("foo", "bar")
  .finish();

// bulk insert a list of values
// `Option::None` is a null value
builder.extend([None, Some(Variant::from("norm"))]);

// create the final VariantArray
let variant_array = builder.build();
assert_eq!(variant_array.len(), 5);
// // Access the values
// row 1 is not null and is an integer
assert!(!variant_array.is_null(0));
assert_eq!(variant_array.value(0), Variant::from(42i32));
// row 1 is null
assert!(variant_array.is_null(1));
// row 2 is not null and is an object
assert!(!variant_array.is_null(2));
let value = variant_array.value(2);
let obj = value.as_object().expect("expected object");
assert_eq!(obj.get("foo"), Some(Variant::from("bar")));
// row 3 is null
assert!(variant_array.is_null(3));
// row 4 is not null and is a short string
assert!(!variant_array.is_null(4));
let value = variant_array.value(4);
assert_eq!(value, Variant::ShortString(ShortString::try_new("norm").unwrap()));

Fields

nulls: NullBufferBuilder

Nulls

metadata_builder: WritableMetadataBuilder

builder for all the metadata

metadata_offsets: Vec<usize>

ending offset for each serialized metadata dictionary in the buffer

value_builder: ValueBuilder

builder for values

value_offsets: Vec<usize>

ending offset for each serialized variant value in the buffer

fields: Fields

The fields of the final StructArray

TODO: 1) Add extension type metadata TODO: 2) Add support for shredding

Implementations

impl VariantArrayBuilder

pub fn new(row_capacity: usize) -> Self

pub fn build(self) -> VariantArray

Build the final builder

pub fn append_null(&mut self)

Appends a null row to the builder.

pub fn append_variant(&mut self, variant: Variant<'_, '_>)

Append the [Variant] to the builder as the next row

fn parent_state(&mut self) -> ParentState<'_, ArrayBuilderState<'_>>

Creates a builder-specific parent state

Trait Implementations

impl Debug for VariantArrayBuilder

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

Formats the value using the given formatter.

impl<'m, 'v> Extend<Option<Variant<'m, 'v>>> for VariantArrayBuilder

fn extend<T: IntoIterator<Item = Option<Variant<'m, '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.

impl VariantBuilderExt for VariantArrayBuilder

fn append_null(&mut self)

Appending NULL to a variant array produces an actual NULL value

type State<'a> = ArrayBuilderState<'a> where Self: 'a

The builder specific state used by nested builders

fn append_value<'m, 'v>(&mut self, value: impl Into<Variant<'m, 'v>>)

Appends a new variant value to this builder. See e.g. [VariantBuilder::append_value].

fn try_new_list( &mut self, ) -> Result<ListBuilder<'_, Self::State<'_>>, ArrowError>

Creates a nested list builder. See e.g. [VariantBuilder::new_list]. Returns an error if the nested builder cannot be created, see e.g. [ObjectBuilder::try_new_list].

fn try_new_object( &mut self, ) -> Result<ObjectBuilder<'_, Self::State<'_>>, ArrowError>

Creates a nested object builder. See e.g. [VariantBuilder::new_object]. Returns an error if the nested builder cannot be created, see e.g. [ObjectBuilder::try_new_object].

fn new_list(&mut self) -> ListBuilder<'_, Self::State<'_>>

Creates a nested list builder. See e.g. [VariantBuilder::new_list]. Panics if the nested builder cannot be created, see e.g. [ObjectBuilder::new_list].

fn new_object(&mut self) -> ObjectBuilder<'_, Self::State<'_>>

Creates a nested object builder. See e.g. [VariantBuilder::new_object]. Panics if the nested builder cannot be created, see e.g. [ObjectBuilder::new_object].