Struct NamedMultiValues 

pub struct NamedMultiValues { /* private fields */ }

Named multiple values

A container that associates a readable name with a set of MultiValues, suitable for organizing data in key-value (name-multiple values) scenarios, such as configuration items, command-line parameter aggregation, structured log fields, etc.

Features

• Provides clear name identification for multiple value collections
• Exposes the inner MultiValues through explicit accessors
• Supports serde serialization and deserialization

Use Cases

• Aggregating a set of ports, hostnames, etc., as semantically meaningful fields
• Outputting named multiple value lists in configurations/logs

Deserialization boundaries

Deserialize validates the V1 wire schema and requires a collection payload, but it does not create a resource budget by itself. For a complete, untrusted JSON document, use NamedMultiValues::decode_json_slice or NamedMultiValues::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::{NamedMultiValues, MultiValues};

// Identify a group of ports with the name "ports"
let named = NamedMultiValues::new(
    "ports",
    MultiValues::Int32(vec![8080, 8081, 8082])
);

assert_eq!(named.name(), "ports");
assert_eq!(named.values().len(), 3);

The wrapper intentionally does not forward MultiValues methods implicitly:

use qubit_value::{MultiValues, NamedMultiValues};

let named = NamedMultiValues::new("ports", MultiValues::Int32(vec![8080]));
let _ = named.len();

Implementations

impl NamedMultiValues

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

Create a new named multiple values

Associates a given name with MultiValues, generating a container that can be referenced by name.

Type Parameters

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

Use Cases

• Building configuration fields (e.g., servers, ports, etc.)
• Binding parsed multiple value results to semantic names

Parameters

• name - Name of the multiple values
• value - Content of the multiple values

Returns

Returns a newly created named multiple values

Examples

use qubit_value::{NamedMultiValues, MultiValues};

let named = NamedMultiValues::new(
    "servers",
    MultiValues::String(vec!["s1".to_string(), "s2".to_string()])
);
assert_eq!(named.name(), "servers");

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

Available on crate feature json only.

Decodes a complete named collection JSON document with default limits.

Parameters

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

Returns

The decoded named collection.

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 collection JSON document with explicit limits.

The wrapper name and nested collection share one accounting session.

Parameters

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

Returns

The decoded named collection.

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 collection into a bounded compact JSON vector with the default V1 JSON resource profile.

Returns

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

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 collection into a bounded compact JSON vector.

Parameters

• limits - Resource limits enforced during JSON encoding.

Returns

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

Errors

Returns ValueWireEncodeError when encoding exceeds limits or the named collection 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 collection to a writer with the default V1 JSON profile.

Type Parameters

• W - Destination writer type.

Parameters

• writer - Destination receiving the complete named collection.

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 collection to a writer after enforcing JSON budgets.

Type Parameters

• W - Destination writer type.

Parameters

• writer - Destination receiving the complete named collection.
• 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 collection cannot be serialized, or writer rejects output.

pub fn name(&self) -> &str

Borrows the human-readable label without allocating or inspecting the collection.

The slice remains valid while this container is borrowed.

Returns

Returns a string slice of the name

Examples

use qubit_value::{NamedMultiValues, MultiValues};

let named = NamedMultiValues::new("items", MultiValues::Int32(vec![1, 2, 3]));
assert_eq!(named.name(), "items");

pub fn values(&self) -> &MultiValues

Borrows the collection without cloning its elements or its label.

Returns

A shared reference to the contained MultiValues.

pub fn values_mut(&mut self) -> &mut MultiValues

Exclusively borrows the collection so it can be changed without changing the label.

Returns

An exclusive reference to the contained MultiValues.

pub fn first_named_value(&self) -> NamedValue

Convert this named multi-values into a named single value.

The returned value keeps the same name and uses the first element from the inner MultiValues. If there is no element, the returned value is Value::Unset with the same data type.

Returns

A named clone of the first item, or a named typed unset value.

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

Replaces the owned label while preserving the collection unchanged.

Converts the supplied name into owned storage and drops the previous label.

Type Parameters

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

Parameters

• name - Human-readable label to associate with the existing collection.

Returns

No return value

Examples

use qubit_value::{NamedMultiValues, MultiValues};

let mut named = NamedMultiValues::new("old", MultiValues::Bool(vec![true]));
named.set_name("new");
assert_eq!(named.name(), "new");

pub fn set_values(&mut self, values: MultiValues)

Replaces the contained values.

Parameters

• values - New collection to store under the existing name.

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

Consumes this wrapper and returns its owned name and values.

Returns

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

pub fn into_first_named_value(self) -> NamedValue

Consumes this container and converts its first item to a named value.

The owned name and first stored item are moved into the result. An empty or unset collection produces crate::Value::Unset with the same data type.

Returns

A named owned first item, or a named typed unset value.

Trait Implementations

impl Clone for NamedMultiValues

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 NamedMultiValues

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for NamedMultiValues

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

where D: Deserializer<'de>,

Deserializes a named collection from the V1 wire contract.

This implementation validates the wire schema and collection shape, but inherits resource accounting from deserializer. Callers handling a complete, untrusted JSON document should use the bounded JSON helpers on NamedMultiValues 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 collection envelope.

Returns

The decoded name and homogeneous collection.

Errors

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

impl Eq for NamedMultiValues

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 NamedMultiValues

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 NamedMultiValues

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

Equality operator ==.

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

Inequality operator !=.

impl Redact for NamedMultiValues

Available on crate feature redact only.

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

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

Parameters

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

impl Serialize for NamedMultiValues

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

where S: Serializer,

Serializes the name and its explicitly versioned collection.

Type Parameters

• S - Serde serializer that determines the output representation.

Parameters

• serializer - Destination receiving the named V1 collection envelope.

Returns

The serializer’s success value after writing the envelope.

Errors

Returns S::Error if wire conversion or serialization fails.

impl StructuralPartialEq for NamedMultiValues