Struct Metadata 

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

A structured, ordered, type-safe key-value store for attaching arbitrary annotations to domain objects.

Metadata is backed by a BTreeMap<String, Value> (ordered by key) and provides two layers of typed access:

• Convenience accessors like Metadata::get and Metadata::set keep the API terse and ergonomic.
• Explicit accessors like Metadata::try_get and Metadata::try_set preserve failure reasons, which is useful for debugging and validation.

The type model intentionally stays JSON-shaped rather than closed over a fixed enum of Rust scalar types. This keeps the crate interoperable with serde_json, nested objects, and external JSON-based APIs.

Examples

use qubit_metadata::Metadata;

let mut meta = Metadata::new();
meta.set("author", "alice");
meta.set("priority", 3_i64);
meta.set("reviewed", true);

// Convenience API
let author: Option<String> = meta.get("author");
assert_eq!(author.as_deref(), Some("alice"));

// Explicit API
let priority = meta.try_get::<i64>("priority").unwrap();
assert_eq!(priority, 3);

Implementations

impl Metadata

pub fn new() -> Self

Creates an empty Metadata instance.

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: DeserializeOwned,

Retrieves and deserializes the value associated with key.

This is the convenience version of Metadata::try_get. It returns None when the key is absent or when deserialization into T fails.

Use this when a concise, best-effort lookup is preferred over detailed diagnostics.

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

where T: DeserializeOwned,

Retrieves and deserializes the value associated with key, preserving the reason when retrieval fails.

Errors

• MetadataError::MissingKey if key does not exist
• MetadataError::DeserializationError if the stored JSON value cannot be deserialized into T

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

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

pub fn value_kind(&self, key: &str) -> Option<MetadataValueKind>

Returns the coarse JSON kind of the value stored under key.

This is a lightweight inspection API inspired by the stricter type introspection facilities in qubit-value, adapted to Metadata’s open-ended JSON storage model.

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

where T: DeserializeOwned,

Retrieves and deserializes the value associated with key, or returns default if lookup fails for any reason.

This mirrors the forgiving default-value style used by qubit-config. It is intentionally convenience-oriented: both missing keys and type mismatches fall back to the supplied default.

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

where T: Serialize,

Serializes value and inserts it under key.

This is the convenience version of Metadata::try_set. It preserves the current ergonomic API and panics if serialization fails.

pub fn try_set<T>( &mut self, key: impl Into<String>, value: T, ) -> MetadataResult<Option<Value>>

where T: Serialize,

Serializes value and inserts it under key, preserving serialization failures instead of panicking.

Errors

Returns MetadataError::SerializationError when value fails to serialize into serde_json::Value.

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

Inserts a raw Value directly, bypassing serialization.

Returns the previous value if present.

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

Removes the entry for key and returns the raw 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 raw 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 all entries from both self and other. Entries in 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 into its underlying BTreeMap.

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 Item = (&'a String, &'a Value)

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Metadata

type Item = (String, Value)

The type of the elements being iterated over.

type IntoIter = IntoIter<String, Value>

Which kind of iterator are we turning this into?

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