Struct Metadata 

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

A structured, ordered, typed key-value store for metadata fields.

Metadata stores values as qubit_value::Value, preserving concrete Rust scalar types such as i64, u32, f64, String, and bool. This avoids the ambiguity of a single JSON number type while still allowing callers to store explicit Value::Json values when they really need JSON payloads.

Use Metadata::with for fluent construction and Metadata::set when mutating an existing object.

Implementations

impl Metadata

pub fn new() -> Self

Creates an empty metadata object.

pub fn is_empty(&self) -> bool

Returns true if there are no entries.

pub fn len(&self) -> usize

Returns the number of key-value pairs.

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

Returns true if the given key exists.

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

where T: DataTypeOf + FromMetadataValue,

Retrieves the value associated with key and converts it to T.

This convenience method returns None when the key is absent or when the stored Value cannot be converted to T.

pub fn try_get<T>(&self, key: &str) -> MetadataResult<T>

where T: DataTypeOf + FromMetadataValue,

Retrieves the value associated with key and converts it to T.

Errors

Returns MetadataError::MissingKey when the key is absent, or MetadataError::TypeMismatch when the stored value cannot be converted to the requested type.

pub fn get_raw(&self, key: &str) -> Option<&Value>

Returns a reference to the stored Value for key, or None if absent.

pub fn data_type(&self, key: &str) -> Option<DataType>

Returns the concrete data type of the value stored under key.

pub fn get_or<T>(&self, key: &str, default: T) -> T

where T: DataTypeOf + FromMetadataValue,

Retrieves and converts the value associated with key, or returns default if lookup or conversion fails.

pub fn set<T>(&mut self, key: &str, value: T) -> Option<Value>

where T: IntoMetadataValue,

Inserts a typed value under key and returns the previous value if present.

pub fn set_checked<T>( &mut self, schema: &MetadataSchema, key: &str, value: T, ) -> MetadataResult<Option<Value>>

where T: IntoMetadataValue,

Inserts a typed value after validating it against schema.

Errors

Returns MetadataError::UnknownField when key is rejected by the schema, or MetadataError::TypeMismatch when the constructed value’s concrete type does not match the schema field type.

pub fn with_checked<T>( self, schema: &MetadataSchema, key: &str, value: T, ) -> MetadataResult<Self>

where T: IntoMetadataValue,

Returns a new metadata object with a typed value validated and inserted.

Errors

Returns MetadataError::UnknownField when key is rejected by the schema, or MetadataError::TypeMismatch when the constructed value’s concrete type does not match the schema field type.

pub fn with<T>(self, key: &str, value: T) -> Self

where T: IntoMetadataValue,

Returns a new metadata object with key set to value.

pub fn set_raw(&mut self, key: &str, value: Value) -> Option<Value>

Inserts a raw Value directly and returns the previous value if present.

pub fn with_raw(self, key: &str, value: Value) -> Self

Returns a new metadata object with a raw Value inserted.

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

Removes the entry for key and returns the stored Value if it existed.

pub fn clear(&mut self)

Removes all entries.

pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)>

Returns an iterator over (&str, &Value) pairs in key-sorted order.

pub fn keys(&self) -> impl Iterator<Item = &str>

Returns an iterator over the keys in sorted order.

pub fn values(&self) -> impl Iterator<Item = &Value>

Returns an iterator over the values in key-sorted order.

pub fn merge(&mut self, other: Metadata)

Merges all entries from other into self, overwriting existing keys.

pub fn merged(&self, other: &Metadata) -> Metadata

Returns a new Metadata that contains entries from self and other.

Entries from other take precedence on key conflicts.

pub fn retain<F>(&mut self, predicate: F)

where F: FnMut(&str, &Value) -> bool,

Retains only the entries for which predicate returns true.

pub fn into_inner(self) -> BTreeMap<String, Value>

Converts this metadata object into its underlying map.

Trait Implementations

impl Clone for Metadata

fn clone(&self) -> Metadata

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() -> Metadata

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Metadata

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Extend<(String, Value)> for Metadata

fn extend<I: IntoIterator<Item = (String, Value)>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬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 From<BTreeMap<String, Value>> for Metadata

fn from(map: BTreeMap<String, Value>) -> Self

Converts to this type from the input type.

impl From<Metadata> for BTreeMap<String, Value>

fn from(meta: Metadata) -> Self

Converts to this type from the input type.

impl FromIterator<(String, Value)> for Metadata

fn from_iter<I: IntoIterator<Item = (String, Value)>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> IntoIterator for &'a Metadata

type IntoIter = Iter<'a, String, Value>

Which kind of iterator are we turning this into?

type Item = (&'a String, &'a Value)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Metadata

type IntoIter = IntoIter<String, Value>

Which kind of iterator are we turning this into?

type Item = (String, Value)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Metadata

fn eq(&self, other: &Metadata) -> 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 Metadata

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Metadata