Struct NamedValue 

pub struct NamedValue { /* private fields */ }

Named single value

Associates a human-readable name with a single Value, facilitating identification, retrieval, and display in configurations, parameter passing, and complex data structures.

Features

• Provides stable name identification for values
• Exposes the inner Value through explicit accessors
• Supports serde serialization and deserialization

Use Cases

• Configuration item encapsulation (e.g., "port", "timeout", etc.)
• Named output of key values in logs/monitoring
• Quick location by name in collections

Deserialization boundaries

Deserialize validates the V1 wire schema and requires a scalar payload, but it does not create a resource budget by itself. For a complete, untrusted JSON document, use NamedValue::decode_json_slice or NamedValue::decode_json_slice_with_limits. When this type is embedded in a larger document, deserialize it through a resource-bounded outer decoder. Bounded helpers report target-deserialization failures as InvalidJson metadata containing only the Serde category and location. Generic Serde errors retain the surrounding deserializer’s semantics and may include input-derived text, such as field names. Reader and writer I/O error sources may also contain application-defined details. Resource limits do not sanitize diagnostics; apply the application’s logging policy to all error sources.

Examples

use qubit_value::{NamedValue, Value};

let named = NamedValue::new("flag", Value::Bool(true));
assert!(named.value().get_bool().unwrap());

The wrapper intentionally does not forward Value methods implicitly:

use qubit_value::{NamedValue, Value};

let named = NamedValue::new("flag", Value::Bool(true));
let _ = named.get_bool();

Implementations

impl NamedValue

pub fn new(name: impl Into<String>, value: Value) -> Self

Create a new named value

Converts the name into owned storage and moves value into the wrapper without cloning it. The name is not required to be unique or nonempty.

Type Parameters

• impl Into<String> - Name source converted into owned storage.

Parameters

• name - Label converted into an owned string.
• value - Scalar payload whose ownership is transferred to the wrapper.

Returns

Returns a newly created NamedValue instance

Examples

use qubit_value::{NamedValue, Value};

let named = NamedValue::new("timeout", Value::Int32(30));
assert_eq!(named.name(), "timeout");

pub fn decode_json_slice(input: &[u8]) -> Result<Self, ValueWireDecodeError>

Available on crate feature json only.

Decodes a complete named scalar JSON document with default limits.

Parameters

• input - Complete UTF-8 JSON document to decode.

Returns

The decoded named scalar.

Errors

Returns a JSON, wire-contract, or resource-limit error.

pub fn decode_json_slice_with_limits( input: &[u8], limits: JsonDecodeLimits, ) -> Result<Self, ValueWireDecodeError>

Available on crate feature json only.

Decodes a complete named scalar JSON document with explicit limits.

The wrapper name and nested scalar share one accounting session.

Parameters

• input - Complete UTF-8 JSON document to decode.
• limits - Input and decoded-resource limits.

Returns

The decoded named scalar.

Errors

Returns a JSON, wire-contract, or resource-limit error.

pub fn to_json_vec(&self) -> Result<Vec<u8>, ValueWireEncodeError>

Available on crate feature json only.

Encodes this named scalar into a bounded compact JSON vector with the default V1 JSON resource profile.

Returns

Compact UTF-8 JSON bytes for the complete named scalar.

Errors

Returns ValueWireEncodeError for resource or serialization failures.

pub fn to_json_vec_with_limits( &self, limits: JsonEncodeLimits, ) -> Result<Vec<u8>, ValueWireEncodeError>

Available on crate feature json only.

Encodes this named scalar into a bounded compact JSON vector.

Parameters

• limits - Resource limits enforced during JSON encoding.

Returns

Compact UTF-8 JSON bytes for the complete named scalar.

Errors

Returns ValueWireEncodeError when encoding exceeds limits or the named scalar cannot be serialized.

pub fn to_json_writer<W>(&self, writer: W) -> Result<(), ValueWireEncodeError>

where W: Write,

Available on crate feature json only.

Encodes this named scalar to a writer with the default V1 JSON profile.

Type Parameters

• W - Destination writer type.

Parameters

• writer - Destination receiving the complete named scalar document.

Returns

Ok(()) after the complete document is written.

The complete document is buffered and admitted before this method writes its bytes to the destination. Preflight, serialization, or budget rejection does not write this document. An I/O error may leave an accepted prefix in the writer; do not blindly retry a complete document on the same destination.

This method does not explicitly flush the writer. Success means the writer accepted all document bytes, not that they were flushed, persisted, or received by a remote peer. Pass &mut writer to retain ownership of a buffered writer, then call flush() and handle its error separately. Passing an owned writer may invoke that writer’s drop behavior; errors from an implicit drop-time flush are not returned by this method.

Errors

Returns ValueWireEncodeError for resource, serialization, or writer failures.

pub fn to_json_writer_with_limits<W>( &self, writer: W, limits: JsonEncodeLimits, ) -> Result<(), ValueWireEncodeError>

where W: Write,

Available on crate feature json only.

Encodes this named scalar to a writer after enforcing JSON budgets.

Type Parameters

• W - Destination writer type.

Parameters

• writer - Destination receiving the complete named scalar document.
• limits - Resource limits enforced during JSON encoding.

Returns

Ok(()) after the complete document is written.

The complete document is buffered and admitted before this method writes its bytes to the destination. Preflight, serialization, or budget rejection does not write this document. An I/O error may leave an accepted prefix in the writer; do not blindly retry a complete document on the same destination.

This method does not explicitly flush the writer. Success means the writer accepted all document bytes, not that they were flushed, persisted, or received by a remote peer. Pass &mut writer to retain ownership of a buffered writer, then call flush() and handle its error separately. Passing an owned writer may invoke that writer’s drop behavior; errors from an implicit drop-time flush are not returned by this method.

Errors

Returns ValueWireEncodeError when encoding exceeds limits, the named scalar cannot be serialized, or writer rejects output.

pub fn name(&self) -> &str

Get a reference to the name

Borrows the stored label without allocating. The slice remains valid while this wrapper is shared-borrowed, preventing name replacement through the wrapper during that borrow.

Returns

Returns a string slice &str of the name

Examples

use qubit_value::{NamedValue, Value};

let named = NamedValue::new("host", Value::String("localhost".to_string()));
assert_eq!(named.name(), "host");

pub fn value(&self) -> &Value

Borrows the contained value without cloning its payload.

The reference is tied to the shared borrow of this wrapper; mutation through the wrapper requires that borrow to end.

Returns

A shared reference to the contained Value.

pub fn value_mut(&mut self) -> &mut Value

Borrows the contained value exclusively, allowing in-place updates.

The reference is tied to the exclusive borrow of this wrapper. Updates can change the payload or its runtime type without changing the name.

Returns

An exclusive reference to the contained Value.

pub fn set_name(&mut self, name: impl Into<String>)

Set a new name

Converts the new label into owned storage and drops the previous name, leaving the contained value unchanged. Empty and duplicate labels are accepted without validation.

Type Parameters

• impl Into<String> - Name source converted into owned storage.

Parameters

• name - The new name

Examples

use qubit_value::{NamedValue, Value};

let mut named = NamedValue::new("old_name", Value::Bool(true));
named.set_name("new_name");
assert_eq!(named.name(), "new_name");

pub fn set_value(&mut self, value: Value)

Moves a new value into this wrapper and drops the previous payload.

The replacement may change the runtime type or unset state; the stored name is preserved and the new payload is not cloned.

Parameters

• value - New value to store under the existing name.

pub fn into_parts(self) -> (String, Value)

Consumes this wrapper and returns its owned name and value.

Returns

The (name, value) pair without cloning either component.

Trait Implementations

impl Clone for NamedValue

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 NamedValue

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for NamedValue

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserializes a named scalar value from the V1 wire contract.

This implementation validates the wire schema and scalar shape, but inherits resource accounting from deserializer. Callers handling a complete, untrusted JSON document should use the bounded JSON helpers on NamedValue instead of an unbounded Serde entry point. Generic deserializer errors may contain input-derived text. The bounded helpers instead expose only Serde category and location for target deserialization failures; resource limits do not sanitize other errors.

Type Parameters

• D - Serde deserializer that supplies the input and any outer budget.

Parameters

• deserializer - Source containing one named V1 scalar envelope.

Returns

The decoded name and scalar value.

Errors

Returns D::Error for an invalid V1 envelope, an unsupported payload, or a payload whose shape is not scalar.

impl Eq for NamedValue

impl From<NamedValue> for NamedMultiValues

fn from(named: NamedValue) -> Self

Construct NamedMultiValues from NamedValue

Reuses the name and promotes the single value to a MultiValues containing only one element.

Parameters

• named - Named scalar consumed to transfer its name and value.

Returns

A named collection containing the promoted scalar.

impl Hash for NamedValue

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for NamedValue

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

Equality operator ==.

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

Inequality operator !=.

impl Redact for NamedValue

Available on crate feature redact only.

fn write_redacted(&self, writer: &mut RedactionWriter<'_>)

Writes the name and policy-selected value through one session.

Parameters

• writer: Borrowed writer for the active redaction session; receives the classified representation without modifying the source value.

impl Serialize for NamedValue

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serializes the name and its explicitly versioned scalar value.

Type Parameters

• S - Serde serializer that determines the output format.

Parameters

• serializer - Destination serializer receiving the named V1 scalar envelope.

Returns

The serializer’s success value after serializing the complete envelope.

Errors

Returns S::Error when the scalar cannot be represented by the V1 wire contract or the serializer rejects the envelope.

impl StructuralPartialEq for NamedValue