Struct ObjectBuilder 

pub struct ObjectBuilder<'a, S>
where
    S: BuilderSpecificState,
{
    parent_state: ParentState<'a, S>,
    pub(crate) fields: IndexMap<u32, usize>,
    validate_unique_fields: bool,
}

A builder for creating Variant::Object values.

See the examples on VariantBuilder for usage.

Fields

parent_state: ParentState<'a, S>

fields: IndexMap<u32, usize>

validate_unique_fields: bool

Implementations

impl<'a, S> ObjectBuilder<'a, S>

where S: BuilderSpecificState,

pub fn new( parent_state: ParentState<'a, S>, validate_unique_fields: bool, ) -> ObjectBuilder<'a, S>

Creates a new object builder, nested on top of the given parent state.

pub fn insert<'m, 'd, T>(&mut self, key: &str, value: T)

where T: Into<Variant<'m, 'd>>,

Add a field with key and value to the object

See Also

• ObjectBuilder::try_insert for a fallible version.
• ObjectBuilder::with_field for a builder-style API.

Panics

This method will panic if the variant contains duplicate field names in objects when validation is enabled. For a fallible version, use ObjectBuilder::try_insert

pub fn try_insert<'m, 'd, T>( &mut self, key: &str, value: T, ) -> Result<(), ArrowError>

where T: Into<Variant<'m, 'd>>,

Add a field with key and value to the object

See Also

• ObjectBuilder::insert for an infallible version that panics
• ObjectBuilder::try_with_field for a builder-style API.

Note

Attempting to insert a duplicate field name produces an error if unique field validation is enabled. Otherwise, the new value overwrites the previous field mapping without erasing the old value, resulting in a larger variant

pub fn insert_bytes<'m, 'd>( &mut self, key: &str, value: impl Into<Variant<'m, 'd>>, )

Add a field with key and value to the object by copying raw bytes when possible.

For objects and lists, this directly copies their underlying byte representation instead of performing a logical copy, and without touching the metadata builder. For other variant types, this falls back to the standard append behavior.

The caller must ensure that the metadata dictionary is already built and correct for any objects or lists being appended, but the value’s new field name is handled normally.

Panics

This method will panic if the variant contains duplicate field names in objects when validation is enabled. For a fallible version, use ObjectBuilder::try_insert_bytes

pub fn try_insert_bytes<'m, 'd>( &mut self, key: &str, value: impl Into<Variant<'m, 'd>>, ) -> Result<(), ArrowError>

Add a field with key and value to the object by copying raw bytes when possible.

For objects and lists, this directly copies their underlying byte representation instead of performing a logical copy, and without touching the metadata builder. For other variant types, this falls back to the standard append behavior.

The caller must ensure that the metadata dictionary is already built and correct for any objects or lists being appended, but the value’s new field name is handled normally.

Note

When inserting duplicate keys, the new value overwrites the previous mapping, but the old value remains in the buffer, resulting in a larger variant

pub fn with_field<'m, 'd, T>(self, key: &str, value: T) -> ObjectBuilder<'a, S>

where T: Into<Variant<'m, 'd>>,

Builder style API for adding a field with key and value to the object

Same as ObjectBuilder::insert, but returns self for chaining.

pub fn try_with_field<'m, 'd, T>( self, key: &str, value: T, ) -> Result<ObjectBuilder<'a, S>, ArrowError>

where T: Into<Variant<'m, 'd>>,

Builder style API for adding a field with key and value to the object

Same as ObjectBuilder::try_insert, but returns self for chaining.

pub fn with_validate_unique_fields( self, validate_unique_fields: bool, ) -> ObjectBuilder<'a, S>

Enables validation for unique field keys when inserting into this object.

When this is enabled, calling ObjectBuilder::finish will return an error if any duplicate field keys were added using ObjectBuilder::insert.

pub fn new_object<'b>( &'b mut self, key: &'b str, ) -> ObjectBuilder<'b, ObjectState<'b>>

Returns an object builder that can be used to append a new (nested) object to this object.

Panics if the proposed key was a duplicate

WARNING: The builder will have no effect unless/until ObjectBuilder::finish is called.

pub fn try_new_object<'b>( &'b mut self, key: &str, ) -> Result<ObjectBuilder<'b, ObjectState<'b>>, ArrowError>

Returns an object builder that can be used to append a new (nested) object to this object.

Fails if the proposed key was a duplicate

WARNING: The builder will have no effect unless/until ObjectBuilder::finish is called.

pub fn new_list<'b>(&'b mut self, key: &str) -> ListBuilder<'b, ObjectState<'b>>

Returns a list builder that can be used to append a new (nested) list to this object.

Panics if the proposed key was a duplicate

WARNING: The builder will have no effect unless/until ListBuilder::finish is called.

pub fn try_new_list<'b>( &'b mut self, key: &str, ) -> Result<ListBuilder<'b, ObjectState<'b>>, ArrowError>

Returns a list builder that can be used to append a new (nested) list to this object.

Fails if the proposed key was a duplicate

WARNING: The builder will have no effect unless/until ListBuilder::finish is called.

pub fn finish(self)

Finalizes this object and appends it to its parent, which otherwise remains unmodified.

Trait Implementations

impl<'a, S> Debug for ObjectBuilder<'a, S>

where S: Debug + BuilderSpecificState,

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

Formats the value using the given formatter.

impl<'a, 'm, 'v, S, K, V> Extend<(K, V)> for ObjectBuilder<'a, S>

where S: BuilderSpecificState, K: AsRef<str>, V: Into<Variant<'m, 'v>>,

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = (K, V)>,

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.