Struct SectionBuilder 

pub struct SectionBuilder { /* private fields */ }

Builder for creating section instances with validation

Uses Vec internally to support multi-valued fields. Field names are looked up via linear search (fast for typical 3-10 field schemas).

Example

use vsf::schema::{SectionSchema, TypeConstraint};

let schema = SectionSchema::new("image")
    .field("width", TypeConstraint::AnyUnsigned)
    .field("height", TypeConstraint::AnyUnsigned)
    .field("cloudy", TypeConstraint::AnyUnsigned);

// Wire: [d"image" (d"width":u5{1920}) (d"height":u5{1080}) (d"cloudy")]
let section = schema.build()
    .set("width", 1920u32)?
    .set("height", 1080u32)?
    .set_empty("cloudy")?
    .encode()?;

Implementations

impl SectionBuilder

pub fn new(schema: SectionSchema) -> Self

Create new builder from schema (empty fields)

pub fn set<T: IntoVsfType>( self, name: impl AsRef<str>, value: T, ) -> ValidationResult<Self>

Set a field with a single value (replaces existing field if present)

pub fn set_empty(self, name: impl AsRef<str>) -> ValidationResult<Self>

Set an empty field (field present but no values)

pub fn set_multi<T: IntoVsfType>( self, name: impl AsRef<str>, values: Vec<T>, ) -> ValidationResult<Self>

Set a field with multiple values (replaces existing field if present)

pub fn append_multi<T: IntoVsfType>( self, name: impl AsRef<str>, values: Vec<T>, ) -> ValidationResult<Self>

Append a new field with multiple values (does NOT replace existing fields) Use this for repeated fields like (contact: a, b, c)(contact: d, e, f)

pub fn add_value<T: IntoVsfType>( self, name: impl AsRef<str>, value: T, ) -> ValidationResult<Self>

Add a value to an existing field (creates field if not present)

pub fn get(&self, name: &str) -> ValidationResult<&Vec<VsfType>>

Get a field by name (returns the vector of values)

pub fn get_value<T: FromVsfType>(&self, name: &str) -> ValidationResult<T>

Get the first value from a field and extract as a specific Rust type

pub fn get_values(&self, name: &str) -> ValidationResult<Vec<VsfType>>

Get all values from a field

pub fn get_fields(&self, name: &str) -> Vec<&FieldValue>

Get all fields with a given name (for repeated fields) Returns a Vec of references to FieldValue, each containing its values

pub fn encode(&self) -> ValidationResult<Vec<u8>>

Encode to VSF bytes Format: [d“section_name“ (d“field1“:val1,val2) (d“field2“) …] Uses FieldValue.flatten() for each field

pub fn parse( schema: SectionSchema, section_bytes: &[u8], ) -> ValidationResult<Self>

Parse a section from VSF bytes into this builder (high-level, schema-validated)

This is the high-level parsing API that validates against a schema. Enables the parse → modify → encode workflow with type safety.

For low-level schema-agnostic parsing without validation, use crate::VsfSection::parse() instead. That API extracts raw data and gives the caller control over the read pointer.

Format

Fields can have:

• Empty: (d"field_name")
• Single: (d"field_name":value)
• Multi: (d"field_name":val1,val2,val3)

[d"section_name" (d"field1":val1,val2) (d"field2") (d"field3":val)]

Validation

• Section name must match schema name
• Each known field’s values are validated against the schema’s type constraints
• Unknown fields are allowed and ignored (schema defines minimum requirements): their values are still parsed to advance the read pointer but are discarded, so a newer writer’s extra field does not brick an older reader

Use Cases

• Type-safe applications with defined schemas
• Modifying existing sections and re-encoding
• When validation and type constraints matter

For the strict variant that rejects unknown fields, use SectionBuilder::parse_strict.

pub fn parse_strict( schema: SectionSchema, section_bytes: &[u8], ) -> ValidationResult<Self>

Strict variant of SectionBuilder::parse that rejects unknown field names with ValidationError::UnknownField instead of ignoring them.

Use this only when you deliberately want to forbid forward-compatible extension fields; the default parse is forgiving.

pub fn parse_document( schema: SectionSchema, doc: &[u8], expected_signer: Option<[u8; 32]>, ) -> ValidationResult<Self>

Verify a whole VSF document, then parse the section named by schema out of it.

This is the safe, general front door for reading a named section from a document: it makes verification un-skippable. It first runs crate::verification::read_verified over the entire doc (which enforces provenance self-consistency plus either a valid signature or a valid rolling hash — a document carrying neither is rejected), then locates the header TOC entry whose name matches schema.name, bounds-checks its byte range, and delegates to SectionBuilder::parse.

This generalises the hard-coded parse_compressed_image helper (which only ever looked up the "image" section) to any schema name, and adds the mandatory verification step that the raw section parsers skip.

Arguments

• schema - The schema whose name selects the section to parse
• doc - Complete VSF file bytes (header + sections)
• expected_signer - Optional 32-byte Ed25519 pubkey the document’s signature must match (only consulted for signed docs)

Errors

Returns ValidationError::Custom wrapping the verification error if the document cannot be trusted, if no TOC field matches schema.name, or if the field’s byte range falls outside doc.

Trait Implementations

impl Debug for SectionBuilder

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

Formats the value using the given formatter.