Struct TableHelper 

pub struct TableHelper<'ctx, 'table, 'de> {
    pub ctx: &'ctx mut Context<'de>,
    pub table: &'table Table<'de>,
    /* private fields */
}

Guides deserialization of a Table by tracking which fields have been consumed.

Create one via Root::helper for the root table, or Item::table_helper / TableHelper::new for nested tables. Then extract fields with required and optional, and finish with expect_empty to reject unknown keys.

Errors are accumulated in the shared Context rather than failing on the first problem, so a single parse pass can report multiple issues.

Examples

use toml_spanner::{Arena, Deserialize, Item, Context, Failed, TableHelper};

struct Config {
    name: String,
    port: u16,
    debug: bool,
}

impl<'de> Deserialize<'de> for Config {
    fn deserialize(ctx: &mut Context<'de>, value: &Item<'de>) -> Result<Self, Failed> {
        let mut th = value.table_helper(ctx)?;
        let name = th.required("name")?;
        let port = th.required("port")?;
        let debug = th.optional("debug").unwrap_or(false);
        th.expect_empty()?;
        Ok(Config { name, port, debug })
    }
}

Fields

ctx: &'ctx mut Context<'de>

table: &'table Table<'de>

Implementations

impl<'ctx, 't, 'de> TableHelper<'ctx, 't, 'de>

pub fn new(ctx: &'ctx mut Context<'de>, table: &'t Table<'de>) -> Self

Creates a new helper for the given table.

Prefer Item::table_helper when implementing Deserialize, or Root::helper for the root table.

pub fn get_entry(&self, key: &str) -> Option<&'t (Key<'de>, Item<'de>)>

Looks up a key-value entry without marking it as consumed.

This is useful for peeking at a field before deciding how to deserialize it. The entry will still be flagged as unexpected by expect_empty unless it is later consumed by required or optional.

pub fn required_mapped<T>( &mut self, name: &'static str, func: fn(&Item<'de>) -> Result<T, Error>, ) -> Result<T, Failed>

Extracts a required field and transforms it with func.

Looks up name, marks it as consumed, and passes the Item to func. This is useful for parsing string values via Item::parse or applying custom validation without implementing Deserialize.

Errors

Returns Failed if the key is absent or if func returns an error. In both cases the error is pushed onto the shared Context.

pub fn optional_mapped<T>( &mut self, name: &'static str, func: fn(&Item<'de>) -> Result<T, Error>, ) -> Option<T>

Extracts an optional field and transforms it with func.

Returns None if the key is missing (no error recorded) or if func returns an error (the error is pushed onto the Context). The field is marked as consumed so expect_empty will not flag it as unexpected.

pub fn required_item( &mut self, name: &'static str, ) -> Result<&'t Item<'de>, Failed>

Returns the raw Item for a required field.

Like required but skips deserialization, giving direct access to the parsed value. The field is marked as consumed.

Errors

Returns Failed and records a MissingField error if the key is absent.

pub fn optional_item(&mut self, name: &'static str) -> Option<&'t Item<'de>>

Returns the raw Item for an optional field.

Like optional but skips deserialization, giving direct access to the parsed value. Returns None when the key is missing (no error recorded). The field is marked as consumed.

pub fn required_entry( &mut self, name: &'static str, ) -> Result<&'t (Key<'de>, Item<'de>), Failed>

Returns the (Key, Item) pair for a required field.

Use this when you need the key’s Span in addition to the value. The field is marked as consumed.

Errors

Returns Failed and records a MissingField error if the key is absent.

pub fn optional_entry(&mut self, key: &str) -> Option<&'t (Key<'de>, Item<'de>)>

Returns the (Key, Item) pair for an optional field.

Returns None when the key is missing (no error recorded). Use this when you need the key’s Span in addition to the value. The field is marked as consumed.

pub fn required<T: Deserialize<'de>>( &mut self, name: &'static str, ) -> Result<T, Failed>

Deserializes a required field, recording an error if the key is missing.

The field is marked as consumed so expect_empty will not flag it as unexpected.

Errors

Returns Failed if the key is absent or if T::deserialize fails. In both cases the error is pushed onto the shared Context.

pub fn optional<T: Deserialize<'de>>(&mut self, name: &str) -> Option<T>

Deserializes an optional field, returning None if the key is missing or deserialization fails (recording the error in the Context).

The field is marked as consumed so expect_empty will not flag it as unexpected.

pub fn remaining_count(&self) -> usize

Returns the number of unused entries remaining in the table.

pub fn into_remaining(self) -> RemainingEntriesIter<'t, 'de>

Iterate over unused &(Key<'de>, Item<'de>) entries in the table.

pub fn expect_empty(self) -> Result<(), Failed>

Finishes deserialization, recording an error if any fields were not consumed by required or optional.

Call this as the last step in a Deserialize implementation to reject unknown keys.

Errors

Returns Failed and pushes an ErrorKind::UnexpectedKeys error if unconsumed fields remain.