Struct Table 

pub struct Table<'de> { /* private fields */ }

A TOML table, a transient collection of key/value pairs inside an Item.

Table is an intermediate structure for converting between Rust types and TOML through FromToml and ToToml. It is the top level value returned by parse and the value inside any [section] or inline { ... } table.

Entries are stored in insertion order, but the TOML specification defines table keys as unordered. Avoid relying on iteration order for semantic purposes.

Accessing values

Use table["key"] for index access, which returns a MaybeItem that never panics on missing keys and supports chained indexing. Use get or get_mut for Option based access.

For structured extraction, use Item::table_helper to create a TableHelper.

Lookup performance

Direct lookups (get, table["key"]) perform a linear scan over entries, O(n) in the number of keys. For small tables or a handful of lookups, as is typical in TOML, this is fast enough.

For structured conversion of larger tables, use TableHelper via Document::table_helper or Item::table_helper, which use the parser’s hash index for O(1) lookups.

Constructing tables

To build a table programmatically, create one with Table::new and insert entries with Table::insert. An Arena is required because entries are arena allocated.

Iteration

Table implements IntoIterator (both by reference and by value), yielding (Key, Item) pairs.

Implementations

impl<'de> Table<'de>

pub fn new() -> Table<'de>

Creates an empty table in format-hints mode (no source span).

The table starts with automatic style: normalization will choose between inline and header based on content. Call set_style to override.

pub fn try_with_capacity(cap: usize, arena: &'de Arena) -> Option<Table<'de>>

Creates an empty table with pre-allocated capacity.

Returns None if cap exceeds u32::MAX.

pub fn span(&self) -> Span

Returns the source span, or 0..0 if this table was constructed programmatically (format-hints mode).

impl<'de> Table<'de>

pub fn insert(&mut self, key: Key<'de>, value: Item<'de>, arena: &'de Arena)

Inserts a key-value pair, replacing any existing entry with the same key.

Performs an O(n) linear scan for duplicates. Prefer Table::insert_unique when the key is known to be absent.

pub fn insert_unique( &mut self, key: Key<'de>, value: Item<'de>, arena: &'de Arena, )

Inserts a key-value pair without checking for duplicates.

Inserting a duplicate key is sound but the behavior is unspecified. It may panic, produce invalid TOML on emit, or cause deserialization errors.

pub fn len(&self) -> usize

Returns the number of entries.

pub fn is_empty(&self) -> bool

Returns true if the table has no entries.

pub fn get_key_value(&self, name: &str) -> Option<(&Key<'de>, &Item<'de>)>

Linear scan for a key, returning both key and value references.

pub fn get(&self, name: &str) -> Option<&Item<'de>>

Returns a reference to the value for name.

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

Returns a mutable reference to the value for name.

pub fn contains_key(&self, name: &str) -> bool

Returns true if the table contains the key.

pub fn remove_entry(&mut self, name: &str) -> Option<(Key<'de>, Item<'de>)>

Removes the first entry matching name, returning the key-value pair. Uses swap-remove, so the ordering of remaining entries may change.

pub fn entries(&self) -> &[(Key<'de>, Item<'de>)]

Returns a slice of all entries.

pub fn entries_mut(&mut self) -> &mut [(Key<'de>, Item<'de>)]

Returns a slice of all entries.

pub fn iter(&self) -> Iter<'_, (Key<'de>, Item<'de>)>

Returns an iterator over all entries (key-value pairs).

pub fn as_item(&self) -> &Item<'de>

Converts this Table into an Item with the same span and payload.

pub fn into_item(self) -> Item<'de>

Converts this Table into an Item with the same span and payload.

impl<'de> Table<'de>

pub fn style(&self) -> TableStyle

Returns the TableStyle recorded on this table.

pub fn set_style(&mut self, kind: TableStyle)

Pins the TableStyle used when this table is emitted.

Tables built programmatically start out with an unresolved style and emit picks a rendering from their size and contents (inline for small tables, a header otherwise). Calling this method locks in kind so the choice survives emission unchanged.

pub fn clone_in(&self, arena: &'de Arena) -> Table<'de>

Deep-clones this table into arena. Keys and strings are shared with the source.

impl<'de> Table<'de>

pub fn set_ignore_source_order(&mut self)

Available on crate feature to-toml only.

Disables source-position reordering for this table’s immediate entries during emission. Non-recursive: child tables are unaffected.

pub fn ignore_source_order(&self) -> bool

Available on crate feature to-toml only.

Returns true if source-position reordering is disabled for this table.

pub fn set_ignore_source_style(&mut self)

Available on crate feature to-toml only.

Disables copying structural styles (TableStyle/ArrayStyle) from source during reprojection for this table’s immediate entries. Key spans and reprojection indices are still copied. Non-recursive.

pub fn ignore_source_style(&self) -> bool

Available on crate feature to-toml only.

Returns true if source-style copying is disabled for this table.

pub fn is_auto_style(&self) -> bool

Available on crate feature to-toml only.

Returns true if this table has automatic style resolution pending.

Trait Implementations

impl Debug for Table<'_>

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

Formats the value using the given formatter.

impl<'de> Default for Table<'de>

fn default() -> Self

Returns the “default value” for a type.

impl From<&Table<'_>> for OwnedTable

fn from(value: &Table<'_>) -> Self

Converts to this type from the input type.

impl<'de> FromFlattened<'de> for Table<'de>

Available on crate feature from-toml only.

type Partial = Table<'de>

Intermediate accumulator type used during conversion.

fn init() -> Self::Partial

Creates an empty accumulator to collect flattened entries.

fn insert( ctx: &mut Context<'de>, key: &Key<'de>, item: &Item<'de>, partial: &mut Self::Partial, ) -> Result<(), Failed>

Inserts a single key-value pair into the accumulator.

fn finish( _ctx: &mut Context<'de>, parent: &Table<'de>, partial: Self::Partial, ) -> Result<Self, Failed>

Converts the accumulator into the final value after all entries have been inserted. The parent parameter is the table that contained the flattened entries.

impl<'de> Index<&str> for Table<'de>

type Output = MaybeItem<'de>

The returned type after indexing.

fn index(&self, index: &str) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a, 'de> IntoIterator for &'a Table<'de>

type Item = &'a (Key<'de>, Item<'de>)

The type of the elements being iterated over.

type IntoIter = Iter<'a, (Key<'de>, Item<'de>)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, 'de> IntoIterator for &'a mut Table<'de>

type Item = &'a mut (Key<'de>, Item<'de>)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, (Key<'de>, Item<'de>)>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'de> IntoIterator for Table<'de>

type Item = (Key<'de>, Item<'de>)

The type of the elements being iterated over.

type IntoIter = IntoIter<'de>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Table<'_>

fn eq(&self, other: &Self) -> 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 Serialize for Table<'_>

Available on crate feature serde only.

fn serialize<S>(&self, ser: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl ToFlattened for Table<'_>

Available on crate feature to-toml only.

fn to_flattened<'a>( &'a self, arena: &'a Arena, table: &mut Table<'a>, ) -> Result<(), ToTomlError>

Inserts this value’s entries directly into an existing table.

impl ToToml for Table<'_>

Available on crate feature to-toml only.

fn to_toml<'a>(&'a self, arena: &'a Arena) -> Result<Item<'a>, ToTomlError>

Produces a TOML Item representing this value.

fn to_optional_toml<'a>( &'a self, arena: &'a Arena, ) -> Result<Option<Item<'a>>, ToTomlError>

Produces an optional TOML Item representing this value.

impl Send for Table<'_>

impl Sync for Table<'_>