Struct VariantObject

pub struct VariantObject<'m, 'v> {
    pub metadata: VariantMetadata<'m>,
    pub value: &'v [u8],
    header: VariantObjectHeader,
    num_elements: u32,
    first_field_offset_byte: u32,
    first_value_byte: u32,
    validated: bool,
}

A Variant Object (struct with named fields).

See the Variant spec file for more information.

Validation

Every instance of variant object is either valid or invalid. depending on whether the underlying bytes are a valid encoding of a variant object subtype (see below).

Instances produced by Self::try_new or Self::with_full_validation are fully (and recursively) validated. They always contain valid data, and infallible accesses such as iteration and indexing are panic-free. The validation cost is linear in the number of underlying bytes.

Instances produced by Self::new are unvalidated and so they may contain either valid or invalid data. Infallible accesses such as iteration and indexing will panic if the underlying bytes are invalid, and fallible alternatives such as Self::iter_try and Self::get are provided as panic-free alternatives. Self::with_full_validation can also be used to validate an unvalidated instance, if desired.

Unvalidated instances can be constructed in constant time. They can be useful if the caller knows the underlying bytes were already validated previously, or if the caller intends to perform a small number of (fallible) field accesses against a large object.

A validated instance guarantees that:

• header byte is valid
• num_elements is in bounds
• field id array is in bounds
• field offset array is in bounds
• field value array is in bounds
• all field ids are valid metadata dictionary entries (*)
• field ids are lexically ordered according by their corresponding string values (*)
• all field offsets are in bounds (*)
• all field values are (recursively) valid variant values (*)
• the associated variant metadata is valid (*)

NOTE: Self::new only skips expensive (non-constant cost) validation checks (marked by (*) in the list above); it panics any of the other checks fails.

Safety

Even an invalid variant object instance is still safe to use in the Rust sense. Accessing it with infallible methods may cause panics but will never lead to undefined behavior.

Fields

metadata: VariantMetadata<'m>

value: &'v [u8]

header: VariantObjectHeader

num_elements: u32

first_field_offset_byte: u32

first_value_byte: u32

validated: bool

Implementations

impl<'m, 'v> VariantObject<'m, 'v>

pub fn new(metadata: VariantMetadata<'m>, value: &'v [u8]) -> Self

pub fn try_new( metadata: VariantMetadata<'m>, value: &'v [u8], ) -> Result<Self, ArrowError>

Attempts to interpet metadata and value as a variant object.

Validation

This constructor verifies that value points to a valid variant object value. In particular, that all field ids exist in metadata, and all offsets are in-bounds and point to valid objects.

pub(crate) fn try_new_with_shallow_validation( metadata: VariantMetadata<'m>, value: &'v [u8], ) -> Result<Self, ArrowError>

Attempts to interpet metadata and value as a variant object, performing only basic (constant-cost) validation.

pub fn is_fully_validated(&self) -> bool

True if this instance is fully validated for panic-free infallible accesses.

pub fn with_full_validation(self) -> Result<Self, ArrowError>

Performs a full validation of this variant object.

pub fn len(&self) -> usize

Returns the number of key-value pairs in this object

pub fn is_empty(&self) -> bool

Returns true if the object contains no key-value pairs

pub fn field(&self, i: usize) -> Option<Variant<'m, 'v>>

Get a field’s value by index in 0..self.len()

Panics

If the index is out of bounds. Also if variant object is corrupted (e.g., invalid offsets or field IDs). The latter can only happen when working with an unvalidated object produced by Self::new.

pub fn try_field(&self, i: usize) -> Result<Variant<'m, 'v>, ArrowError>

Fallible version of field. Returns field value by index, capturing validation errors

fn try_field_with_shallow_validation( &self, i: usize, ) -> Result<Variant<'m, 'v>, ArrowError>

fn get_offset(&self, i: usize) -> Result<u32, ArrowError>

pub fn field_name(&self, i: usize) -> Option<&'m str>

Get a field’s name by index in 0..self.len()

Panics

If the variant object is corrupted (e.g., invalid offsets or field IDs). This should never happen since the constructor validates all data upfront.

fn try_field_name(&self, i: usize) -> Result<&'m str, ArrowError>

Fallible version of field_name. Returns field name by index, capturing validation errors

pub fn iter(&self) -> impl Iterator<Item = (&'m str, Variant<'m, 'v>)> + '_

Returns an iterator of (name, value) pairs over the fields of this object.

pub fn iter_try( &self, ) -> impl Iterator<Item = Result<(&'m str, Variant<'m, 'v>), ArrowError>> + '_

Fallible iteration over the fields of this object.

fn iter_try_with_shallow_validation( &self, ) -> impl Iterator<Item = Result<(&'m str, Variant<'m, 'v>), ArrowError>> + '_

pub fn get(&self, name: &str) -> Option<Variant<'m, 'v>>

Returns the value of the field with the specified name, if any.

Ok(None) means the field does not exist; Err means the search encountered an error.

Trait Implementations

impl<'m, 'v> Clone for VariantObject<'m, 'v>

fn clone(&self) -> VariantObject<'m, 'v>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'m, 'v> Debug for VariantObject<'m, 'v>

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

Formats the value using the given formatter.

impl<'m, 'v> PartialEq for VariantObject<'m, 'v>

fn eq(&self, other: &VariantObject<'m, 'v>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'m, 'v> StructuralPartialEq for VariantObject<'m, 'v>