Struct Metadata 

pub struct Metadata(/* private fields */);

An ordered dictionary of named diagnostic values belonging to a single error context.

Functions returning metadata document the keys and their meaning. crate::Exn::metadata() and crate::Error::metadata() yield non-empty dictionaries separately; dictionaries from independent causes are never merged. Keys are iterated and formatted in lexicographic order. Debug formatting and Message’s display omit key quotes for non-empty names containing only ASCII letters, digits, _, -, or .. Other keys use quoted, escaped string formatting.

Common schemas

These schemas define conventional keys, not required fields. Store only information already available at the failure site; do not collect additional information just to populate a schema. Omitted keys mean the information was not recorded, not that it was empty or absent. Functions returning metadata document which keys they provide. Metadata alone does not establish a semantic classification or whether recovery is safe.

Input validation

Key	Value	Meaning
input	Any MetadataValue	The offending input, preserving its original representation where possible.

Use Message::with_input() to record already-known input. This convention also applies to malformed data classified as Class::Corruption; attaching input does not imply Class::Validation. Do not record secrets or other sensitive input that should not appear in diagnostics.

External program runtime failure

Key	Value	Meaning
program	MetadataValue::Path	The invoked program name or path, without resolving it.
exit_status	MetadataValue::String	The display representation of std::process::ExitStatus, including termination without an exit code.
exit_code	MetadataValue::I64	The exit code, when std::process::ExitStatus::code() returns one.
stdout	MetadataValue::Bytes	Captured standard output, without text decoding.
stderr	MetadataValue::Bytes	Captured standard error, without text decoding.

Use Message::with_command_status() to record program, exit_status, and an available exit_code together, or Message::with_command_output() to include already-captured output. Message::with_program() and Message::with_exit_status() record the fields available at spawn failures or after program identity was lost.

A failed exit status does not by itself establish a recovery class. Preserve native errors from spawning or communicating with a program as causes; their contexts can also use program, without an exit status or output.

Implementations

impl Metadata

pub fn new() -> Self

Create an empty dictionary.

pub fn len(&self) -> usize

Return the number of values in this dictionary.

pub fn is_empty(&self) -> bool

Return whether this dictionary has no values.

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

Return whether a value is recorded under key.

pub fn get(&self, key: &str) -> Option<&MetadataValue>

Return the value recorded under key, if present.

pub fn get_mut(&mut self, key: &str) -> Option<&mut MetadataValue>

Return a mutable reference to the value recorded under key, if present.

pub fn insert( &mut self, key: impl Into<Cow<'static, str>>, value: impl Into<MetadataValue>, ) -> Option<MetadataValue>

Record value under key, returning any previous value.

pub fn remove(&mut self, key: &str) -> Option<MetadataValue>

Remove and return the value recorded under key, if present.

pub fn clear(&mut self)

Remove all recorded values.

pub fn iter( &self, ) -> impl DoubleEndedIterator<Item = (&Cow<'static, str>, &MetadataValue)> + ExactSizeIterator + '_

Iterate over keys and values in lexicographic key order.

pub fn iter_mut( &mut self, ) -> impl DoubleEndedIterator<Item = (&Cow<'static, str>, &mut MetadataValue)> + ExactSizeIterator + '_

Iterate over keys and mutable values in lexicographic key order.

Trait Implementations

impl Clone for Metadata

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Metadata

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

Formats the value using the given formatter.

impl Default for Metadata

fn default() -> Self

Returns the “default value” for a type.

impl Extend<(Cow<'static, str>, MetadataValue)> for Metadata

fn extend<T: IntoIterator<Item = (Cow<'static, str>, MetadataValue)>>( &mut self, iter: T, )

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<const N: usize> From<[(Cow<'static, str>, MetadataValue); N]> for Metadata

fn from(values: [(Cow<'static, str>, MetadataValue); N]) -> Self

Converts to this type from the input type.

impl FromIterator<(Cow<'static, str>, MetadataValue)> for Metadata

fn from_iter<T: IntoIterator<Item = (Cow<'static, str>, MetadataValue)>>( iter: T, ) -> Self

Creates a value from an iterator.

impl Index<&str> for Metadata

type Output = MetadataValue

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl PartialEq for Metadata

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Metadata