Struct VariantList

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

Variant Array.

See the Variant spec for details.

NOTE: The “list” naming differs from the variant spec – which calls it “array” – in order to be consistent with Parquet and Arrow type naming. Otherwise, the name would conflict with the VariantArray : Array we must eventually define for variant-typed arrow arrays.

Validation

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

Instances produced by Self::try_new or Self::with_full_validation are fully 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. This 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) accesses to a large list.

A validated variant list instance guarantees that:

• header byte is valid
• num_elements is in bounds
• offset array content is in-bounds
• first offset is zero
• last offset is in-bounds
• all other offsets are in-bounds (*)
• all offsets are monotonically increasing (*)
• all values are (recursively) valid variant objects (*)
• 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 list 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: VariantListHeader

num_elements: u32

first_value_byte: u32

validated: bool

Implementations

impl<'m, 'v> VariantList<'m, 'v>

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

Attempts to interpret value as a variant array value.

Validation

This constructor verifies that value points to a valid variant array value. In particular, that all offsets are in-bounds and point to valid (recursively validated) objects.

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

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 array, 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 array and returns the result.

pub fn len(&self) -> usize

Return the length of this array

pub fn is_empty(&self) -> bool

Is the array of zero length

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

Returns element by index in 0..self.len(), if any. May panic if this list is invalid.

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

Fallible version of get. Returns element by index, capturing validation errors

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

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

Iterates over the values of this list. When working with unvalidated input, consider Self::iter_try to avoid panics due to invalid data.

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

Fallible iteration over the elements of this list.

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

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

Trait Implementations

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

fn clone(&self) -> VariantList<'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 VariantList<'m, 'v>

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

Formats the value using the given formatter.

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

fn eq(&self, other: &VariantList<'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 VariantList<'m, 'v>