Struct TupleDecoder 

pub struct TupleDecoder { /* private fields */ }

Decodes fields from Binary Tuples according to a fixed schema.

Reusable: create once per schema, decode many tuples. Precomputes byte offsets for O(1) field access.

Implementations

impl TupleDecoder

pub fn new(schema: &StrictSchema) -> Self

Create a decoder for the given schema.

pub fn schema_version(&self, tuple: &[u8]) -> Result<u32, StrictError>

Read and validate the header, then return the schema version.

Validates magic bytes at [0..4] and format version at [4] before returning the schema version at [5..9].

pub fn is_null(&self, tuple: &[u8], col_idx: usize) -> Result<bool, StrictError>

Check whether column col_idx is null in the given tuple.

pub fn extract_fixed_raw<'a>( &self, tuple: &'a [u8], col_idx: usize, ) -> Result<Option<&'a [u8]>, StrictError>

Extract raw bytes for a fixed-size column. Returns None if null.

This is the O(1) fast path: a single bounds check + pointer slice.

pub fn extract_variable_raw<'a>( &self, tuple: &'a [u8], col_idx: usize, ) -> Result<Option<&'a [u8]>, StrictError>

Extract raw bytes for a variable-length column. Returns None if null.

Reads two entries from the offset table to determine start and length.

pub fn extract_value( &self, tuple: &[u8], col_idx: usize, ) -> Result<Value, StrictError>

Extract a column value as a Value, performing type-aware decoding.

This is the general-purpose extraction path. For hot paths, prefer extract_fixed_raw / extract_variable_raw to avoid Value allocation.

pub fn extract_all(&self, tuple: &[u8]) -> Result<Vec<Value>, StrictError>

Extract all columns from a tuple into a Vec.

pub fn extract_by_name( &self, tuple: &[u8], name: &str, ) -> Result<Value, StrictError>

Extract a column by name.

pub fn extract_value_versioned( &self, tuple: &[u8], col_idx: usize, old_col_count: usize, ) -> Result<Value, StrictError>

Decode a tuple written with an older schema version.

Columns present in the old schema are extracted normally. Columns added in newer schema versions return their declared default value, or Value::Null for nullable columns without a default.

old_col_count is the number of columns in the schema version that wrote this tuple.

Correctness invariant: a non-nullable column added via ALTER ADD COLUMN ... NOT NULL DEFAULT <expr> will always return the materialized default, never Value::Null. The ALTER path rejects NOT NULL without a DEFAULT, so every non-nullable column in the schema must have col.default populated.

pub fn schema(&self) -> &StrictSchema

Access the schema this decoder was built for.

pub fn extract_bitemporal_timestamps( &self, tuple: &[u8], ) -> Result<(i64, i64, i64), StrictError>

Extract the three bitemporal timestamps from a tuple: (system_from_ms, valid_from_ms, valid_until_ms). Only valid for schemas constructed with StrictSchema::new_bitemporal.

pub fn fixed_section_start(&self) -> usize

Byte offset where fixed-field section starts.

pub fn offset_table_start(&self) -> usize

Byte offset where the variable offset table starts.

pub fn var_data_start(&self) -> usize

Byte offset where variable data starts.

pub fn var_count(&self) -> usize

Number of variable-length columns in the schema.

pub fn fixed_field_location(&self, col_idx: usize) -> Option<(usize, usize)>

Byte offset and size for a fixed column (relative to tuple start). Returns None if the column is variable-length.

pub fn var_field_index(&self, col_idx: usize) -> Option<usize>

Index in the variable offset table for a column. Returns None if the column is fixed-size.