Enum ParentState 

pub enum ParentState<'a> {
    Variant {
        value_builder: &'a mut ValueBuilder,
        saved_value_builder_offset: usize,
        metadata_builder: &'a mut dyn MetadataBuilder,
        saved_metadata_builder_dict_size: usize,
        finished: bool,
    },
    List {
        value_builder: &'a mut ValueBuilder,
        saved_value_builder_offset: usize,
        metadata_builder: &'a mut dyn MetadataBuilder,
        saved_metadata_builder_dict_size: usize,
        offsets: &'a mut Vec<usize>,
        saved_offsets_size: usize,
        finished: bool,
    },
    Object {
        value_builder: &'a mut ValueBuilder,
        saved_value_builder_offset: usize,
        metadata_builder: &'a mut dyn MetadataBuilder,
        saved_metadata_builder_dict_size: usize,
        fields: &'a mut IndexMap<u32, usize>,
        saved_fields_size: usize,
        finished: bool,
    },
}

Tracks information needed to correctly finalize a nested builder, for each parent builder type.

A child builder has no effect on its parent unless/until its finalize method is called, at which point the child appends the new value to the parent. As a (desirable) side effect, creating a parent state instance captures mutable references to a subset of the parent’s fields, rendering the parent object completely unusable until the parent state goes out of scope. This ensures that at most one child builder can exist at a time.

The redundancy in value_builder and metadata_builder is because all the references come from the parent, and we cannot “split” a mutable reference across two objects (parent state and the child builder that uses it). So everything has to be here. Rust layout optimizations should treat the variants as a union, so that accessing a value_builder or metadata_builder is branch-free.

Variants

Variant

Fields

value_builder: &'a mut ValueBuilder

saved_value_builder_offset: usize

metadata_builder: &'a mut dyn MetadataBuilder

saved_metadata_builder_dict_size: usize

finished: bool

List

Fields

value_builder: &'a mut ValueBuilder

saved_value_builder_offset: usize

metadata_builder: &'a mut dyn MetadataBuilder

saved_metadata_builder_dict_size: usize

offsets: &'a mut Vec<usize>

saved_offsets_size: usize

finished: bool

Object

Fields

value_builder: &'a mut ValueBuilder

saved_value_builder_offset: usize

metadata_builder: &'a mut dyn MetadataBuilder

saved_metadata_builder_dict_size: usize

fields: &'a mut IndexMap<u32, usize>

saved_fields_size: usize

finished: bool

Implementations

impl<'a> ParentState<'a>

pub fn variant( value_builder: &'a mut ValueBuilder, metadata_builder: &'a mut dyn MetadataBuilder, ) -> Self

Creates a new instance suitable for a top-level variant builder (e.g. VariantBuilder). The value and metadata builder state is checkpointed and will roll back on drop, unless Self::finish is called.

pub fn list( value_builder: &'a mut ValueBuilder, metadata_builder: &'a mut dyn MetadataBuilder, offsets: &'a mut Vec<usize>, saved_parent_value_builder_offset: usize, ) -> Self

Creates a new instance suitable for a ListBuilder. The value and metadata builder state is checkpointed and will roll back on drop, unless Self::finish is called. The new element’s offset is also captured eagerly and will also roll back if not finished.

pub fn try_object( value_builder: &'a mut ValueBuilder, metadata_builder: &'a mut dyn MetadataBuilder, fields: &'a mut IndexMap<u32, usize>, saved_parent_value_builder_offset: usize, field_name: &str, validate_unique_fields: bool, ) -> Result<Self, ArrowError>

Creates a new instance suitable for an ObjectBuilder. The value and metadata builder state is checkpointed and will roll back on drop, unless Self::finish is called. The new field’s name and offset are also captured eagerly and will also roll back if not finished.

The call fails if the field name is invalid (e.g. because it duplicates an existing field).

fn value_builder(&mut self) -> &mut ValueBuilder

fn metadata_builder(&mut self) -> &mut dyn MetadataBuilder

fn saved_value_builder_offset(&mut self) -> usize

fn is_finished(&mut self) -> &mut bool

pub fn finish(&mut self)

Mark the insertion as having succeeded. Internal state will no longer roll back on drop.

fn rollback(&mut self)

pub fn value_and_metadata_builders( &mut self, ) -> (&mut ValueBuilder, &mut dyn MetadataBuilder)

Return mutable references to the value and metadata builders that this parent state is using.

Trait Implementations

impl<'a> Debug for ParentState<'a>

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

Formats the value using the given formatter.

impl Drop for ParentState<'_>

Automatically rolls back any unfinished ParentState.

fn drop(&mut self)

Executes the destructor for this type.