Struct Item 

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

A parsed TOML value with span information.

Use the as_* methods (as_str, as_i64, as_table, etc.) to extract the value, or call value / value_mut to pattern match via the Value / ValueMut enums.

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 well fast enough.

For structured deserialization of larger tables, use TableHelper with the Context returned by parse.

Examples

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

Implementations

impl<'de> Item<'de>

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

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

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

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

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

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

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

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

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>

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

This is the typical entry point for implementing Deserialize.

impl<'de> Item<'de>

pub fn kind(&self) -> Kind

pub fn span(&self) -> Span

Returns the byte-offset span of this value in the source document.

pub fn type_str(&self) -> &'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_i64(&self) -> Option<i64>

Returns an i64 if this is an integer value.

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 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 table and is non-empty.

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

Returns true if the value is a table and has the specified key.

impl<'de> Item<'de>

pub fn expected(&self, expected: &'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<'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.