Struct Item 

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

A parsed TOML value with span information.

Extract values with the as_* methods (as_str, as_i64, as_table, etc.) or pattern match via value and value_mut.

Items support indexing with &str (table lookup) and usize (array access). These operators return MaybeItem and never panic. Missing keys or out-of-bounds indices produce a None variant instead.

Lookup performance

String-key lookups (item["key"], as_table + Table::get) perform a linear scan over the table 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 with the Context from parse, which internally uses an index for O(1) lookups.

Examples

let arena = toml_spanner::Arena::new();
let table = toml_spanner::parse("x = 42", &arena).unwrap();
assert_eq!(table["x"].as_i64(), Some(42));
assert_eq!(table["missing"].as_i64(), None);

Implementations

impl<'de> Item<'de>

pub fn require_custom_string( &self, ctx: &mut Context<'de>, expected: &'static &'static str, ) -> Result<&'de str, Failed>

Available on crate feature from-toml only.

Returns a string, or records an error with a custom expected message.

Use instead of require_string when the expected value is more specific than “a string”, for example "an IPv4 address" or "a hex color".

pub fn require_string(&self, ctx: &mut Context<'de>) -> Result<&'de str, Failed>

Available on crate feature from-toml only.

Returns a string, or records an error if this is not a string.

pub fn require_array( &self, ctx: &mut Context<'de>, ) -> Result<&Array<'de>, Failed>

Available on crate feature from-toml only.

Returns an array reference, or records an error if this is not an array.

pub fn require_table( &self, ctx: &mut Context<'de>, ) -> Result<&Table<'de>, Failed>

Available on crate feature from-toml only.

Returns a table reference, or records an error if this is not a table.

pub fn table_helper<'ctx, 'item>( &'item self, ctx: &'ctx mut Context<'de>, ) -> Result<TableHelper<'ctx, 'item, 'de>, Failed>

Available on crate feature from-toml only.

Creates a TableHelper for this item, returning an error if it is not a table.

Typical entry point for implementing FromToml.

impl<'de> Item<'de>

pub fn set_ignore_source_formatting_recursively(&mut self)

Available on crate feature to-toml only.

Prevents this item and its entire subtree from using source formatting during format-preserving emission. The item will be emitted with clean formatted output even when the rest of the document preserves source formatting via reprojection.

pub fn ignore_source_formatting_recursively(&self) -> bool

Available on crate feature to-toml only.

Returns true if this item will skip source formatting during emission.

impl<'de> Item<'de>

pub fn string(s: &'de str) -> Self

Creates a string Item in format-hints mode (no source span).

impl<'de> Item<'de>

pub fn kind(&self) -> Kind

Returns the type discriminant of this value.

pub fn flag(&self) -> u32

Returns the raw 3-bit flag encoding the container sub-kind.

Prefer Table::style or Array::style for a typed alternative.

pub fn span(&self) -> Span

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

pub fn type_str(&self) -> &'static &'static str

Returns the TOML type name (e.g. "string", "integer", "table").

impl<'de> Item<'de>

pub fn value(&self) -> Value<'_, 'de>

Returns a borrowed view for pattern matching.

pub fn value_mut(&mut self) -> ValueMut<'_, 'de>

Returns a mutable view for pattern matching.

impl<'de> Item<'de>

pub fn as_str(&self) -> Option<&str>

Returns a borrowed string if this is a string value.

pub fn as_i128(&self) -> Option<i128>

Returns an i128 if this is an integer value.

pub fn as_i64(&self) -> Option<i64>

Returns an i64 if this is an integer value that fits in the i64 range.

pub fn as_u64(&self) -> Option<u64>

Returns a u64 if this is an integer value that fits in the u64 range.

pub fn as_f64(&self) -> Option<f64>

Returns an f64 if this is a float or integer value.

Integer values are converted to f64 via as cast (lossy for large values outside the 2^53 exact-integer range).

pub fn as_bool(&self) -> Option<bool>

Returns a bool if this is a boolean value.

pub fn as_array(&self) -> Option<&Array<'de>>

Returns a borrowed array if this is an array value.

pub fn as_table(&self) -> Option<&Table<'de>>

Returns a borrowed table if this is a table value.

pub fn as_datetime(&self) -> Option<&DateTime>

Returns a borrowed DateTime if this is a datetime value.

pub fn as_array_mut(&mut self) -> Option<&mut Array<'de>>

Returns a mutable array reference.

pub fn into_table(self) -> Option<Table<'de>>

Consumes this item, returning the table if it is one.

pub fn as_table_mut(&mut self) -> Option<&mut Table<'de>>

Returns a mutable table reference.

pub fn has_keys(&self) -> bool

Returns true if the value is a non-empty table.

pub fn has_key(&self, key: &str) -> bool

Returns true if the value is a table containing key.

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

Clones this item into arena, sharing existing strings.

Scalar values are copied directly. Tables and arrays are recursively cloned with new arena-allocated storage. String values and table key names continue to reference their original memory, so the source arena (or input string) must remain alive.

impl<'de> Item<'de>

pub fn expected(&self, expected: &'static &'static str) -> Error

Creates an “expected X, found Y” error using this value’s type and span.

pub fn parse<T>(&self) -> Result<T, Error>

where T: FromStr, <T as FromStr>::Err: Display,

Takes a string value and parses it via std::str::FromStr.

Returns an error if the value is not a string or parsing fails.

Trait Implementations

impl Debug for Item<'_>

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

Formats the value using the given formatter.

impl<'a> From<&Item<'a>> for OwnedItem

fn from(item: &Item<'a>) -> Self

Creates an OwnedItem by copying item into a single managed allocation.

All strings (keys and values) are copied, and all table/array backing storage is laid out in one contiguous buffer. The result is fully independent of the source arena.

impl<'de> From<&'de str> for Item<'de>

fn from(value: &'de str) -> Self

Converts to this type from the input type.

impl<'de> From<DateTime> for Item<'de>

fn from(value: DateTime) -> Self

Converts to this type from the input type.

impl<'a> From<Item<'a>> for OwnedItem

fn from(item: Item<'a>) -> Self

Creates an OwnedItem by copying item into a single managed allocation.

This is a convenience wrapper that delegates to From<&Item>.

impl<'de> From<bool> for Item<'de>

fn from(value: bool) -> Self

Converts to this type from the input type.

impl<'de> From<f64> for Item<'de>

fn from(value: f64) -> Self

Converts to this type from the input type.

impl<'de> From<i128> for Item<'de>

fn from(value: i128) -> Self

Converts to this type from the input type.

impl<'de> From<i32> for Item<'de>

fn from(value: i32) -> Self

Converts to this type from the input type.

impl<'de> From<i64> for Item<'de>

fn from(value: i64) -> Self

Converts to this type from the input type.

impl<'de> FromFlattened<'de> for Item<'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 Item<'de>

type Output = MaybeItem<'de>

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'de> Index<usize> for Item<'de>

type Output = MaybeItem<'de>

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'de> PartialEq for Item<'de>

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 Item<'_>

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 Item<'_>

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 Item<'_>

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 Item<'_>

impl Sync for Item<'_>