Struct ValueWireV1 

pub struct ValueWireV1 { /* private fields */ }

Stable version-one wire DTO for a scalar or homogeneous collection.

Canonical JSON output is byte-stable for the same value under the supported serde_json version and configuration, with canonical field and object-key order, including recursively nested JSON objects. Other Serde formats may represent this DTO, but their bytes are outside this stability contract. See the crate documentation.

V1 is closed: existing tags, shapes, and payload representations cannot change, and future runtime data types require a new wire version instead of extending V1.

Runtime JSON numbers are accepted only when V1 can reconstruct the same serde_json::Number under the strict qubit-json number model. Numbers that would change identity when round-tripped return the JSON-gated JsonNumberNotRoundTrippable error. This error does not expose the number text.

Deserialization is intentionally available through crate::ValueWireV1Seed, which lets a bounded decoder control the complete input and structure.

Examples

use qubit_value::{Value, ValueWireV1};

let wire = ValueWireV1::try_from(Value::from(42_i32)).unwrap();
let encoded = serde_json::to_string(&wire).unwrap();
assert_eq!(encoded, r#"{"version":1,"value":{"scalar":{"int32":42}}}"#);
assert_eq!(wire.into_container().get_first::<i32>().unwrap(), 42);

Implementations

impl ValueWireV1

pub const VERSION: u8 = VALUE_WIRE_V1_VERSION

Numeric version emitted and accepted by this DTO.

pub const fn new(value: ValueWirePayloadV1) -> Self

Creates a V1 DTO from an already validated V1 payload.

Parameters

• value - Validated ValueWirePayloadV1 moved into the envelope, preserving its exact runtime type and scalar-or-collection shape.

Returns

A V1 DTO containing value.

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

Available on crate feature json only.

Decodes a V1 JSON wire value using the default structural limits.

The complete input length and decoded structure are checked before the value is returned. Embedded protocols should share one qubit_budget::json::JsonDecodeSession across their complete document.

Parameters

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

Returns

The decoded V1 wire DTO.

Errors

Returns a limit error when the input or decoded structure is too large, ValueWireDecodeError::UnsupportedVersion when the envelope declares another supported-width version, or ValueWireDecodeError::Syntax when the input is not one valid JSON document, or ValueWireDecodeError::InvalidJson when valid JSON cannot be decoded as a V1 wire value.

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

Available on crate feature json only.

Decodes a V1 JSON wire value using explicit structural limits.

The complete input length and decoded structure are checked before the value is returned. Embedded values should be checked through the outer protocol’s shared qubit_budget::json::JsonDecodeSession.

Parameters

• input - Complete UTF-8 JSON document to decode.
• limits - Shared encoded-input and structural limits.

Returns

The decoded V1 wire DTO.

Errors

Returns a limit error when input or its decoded structure exceeds limits, ValueWireDecodeError::UnsupportedVersion when the envelope declares another supported-width version, ValueWireDecodeError::Syntax when the input is not one valid JSON document, or ValueWireDecodeError::InvalidJson when valid JSON cannot be decoded as a V1 wire value.

pub fn default_json_decode_limits() -> JsonDecodeLimits

Available on crate feature json only.

Returns the default JSON resource profile for complete V1 documents.

Returns

Decode limits suitable for one standalone V1 envelope.

pub fn default_json_encode_limits() -> JsonEncodeLimits

Available on crate feature json only.

Returns the default JSON resource profile for encoding V1 documents.

Returns

Encode limits suitable for one standalone V1 envelope.

pub const fn container(&self) -> &ValueContainer

Returns the runtime container represented by this DTO.

Returns

A shared reference to the preserved runtime container.

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

Available on crate feature json only.

Encodes this V1 document into a compact JSON vector with default limits.

Returns

The encoded complete V1 document.

Errors

Returns ValueWireEncodeError::Budget when the document exceeds the default JSON resource profile.

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

Available on crate feature json only.

Encodes this V1 document into a bounded compact JSON vector.

Parameters

• limits - Resource limits enforced during encoding.

Returns

Compact UTF-8 JSON bytes for the complete V1 document.

Runs a conservative payload preflight before encoding, then enforces limits authoritatively while encoding the full envelope. The preflight may report a lower-bound budget error and does not bound every preparation allocation.

Errors

Returns ValueWireEncodeError when preflight or final encoding exceeds limits, or the document 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 V1 document to a writer with default limits.

Type Parameters

• W - Destination writer type.

Parameters

• writer - Destination receiving the complete JSON 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::Budget for resource-limit failures or ValueWireEncodeError::Io when writer rejects output.

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

Type Parameters

• W - Destination writer type.

Parameters

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

Returns

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

Runs a conservative payload preflight before encoding, then enforces limits authoritatively while encoding the full envelope. The preflight may report a lower-bound budget error and does not bound every preparation allocation.

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 preflight or final encoding exceeds limits, the document cannot be serialized, or writer rejects output.

pub fn into_container(self) -> ValueContainer

Consumes the DTO and returns its runtime container.

Returns

The preserved runtime container.

Trait Implementations

impl Clone for ValueWireV1

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 ValueWireV1

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

Formats the value using the given formatter.

impl Eq for ValueWireV1

impl From<ValueWireV1> for ValueContainer

fn from(value: ValueWireV1) -> Self

Unwraps the runtime container from a V1 DTO.

Parameters

• value - Owned DTO whose container is moved into the result.

Returns

The preserved runtime container without cloning its payload.

impl Hash for ValueWireV1

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 ValueWireV1

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ValueWireV1

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

where S: Serializer,

Serializes the contained runtime shape through the V1 contract.

Type Parameters

• S - Serde serializer defining the output format and error type.

Parameters

• serializer - Serializer consumed to emit the versioned envelope.

Returns

The serializer’s completed output on success.

Errors

Returns the serializer’s error if it cannot encode the envelope or payload.

impl StructuralPartialEq for ValueWireV1

impl TryFrom<MultiValues> for ValueWireV1

type Error = ValueWireEncodeError

Failure to represent the consumed runtime value under the V1 contract.

fn try_from(values: MultiValues) -> Result<Self, Self::Error>

Wraps a runtime collection in a V1 DTO.

Parameters

• values - Homogeneous collection to validate and consume.

Returns

A V1 DTO preserving the input type and shape.

Errors

Returns ValueWireEncodeError::NonFiniteFloat for a non-finite float element, ValueWireEncodeError::BigDecimalScaleTooLarge for an element whose decimal exponent is outside V1’s supported range, or ValueWireEncodeError::InstantYearOutOfRange for an instant outside the supported UTC year range. With the json feature, returns JsonNumberNotRoundTrippable if any runtime JSON number in the collection, including a nested number, cannot preserve its serde_json::Number identity under the V1 number model.

impl TryFrom<Value> for ValueWireV1

type Error = ValueWireEncodeError

Failure to represent the consumed runtime value under the V1 contract.

fn try_from(value: Value) -> Result<Self, Self::Error>

Wraps a runtime scalar in a V1 DTO.

Parameters

• value - Runtime scalar to validate and consume.

Returns

A V1 DTO preserving the input type and shape.

Errors

Returns ValueWireEncodeError::NonFiniteFloat for a non-finite float, ValueWireEncodeError::BigDecimalScaleTooLarge for a decimal whose exponent is outside V1’s supported range, or ValueWireEncodeError::InstantYearOutOfRange for an instant outside the supported UTC year range. With the json feature, returns JsonNumberNotRoundTrippable if a runtime JSON number, including a nested number, cannot preserve its serde_json::Number identity under the V1 number model.

impl TryFrom<ValueContainer> for ValueWireV1

type Error = ValueWireEncodeError

Failure to represent the consumed runtime value under the V1 contract.

fn try_from(value: ValueContainer) -> Result<Self, Self::Error>

Wraps an explicit runtime shape in a V1 DTO.

Parameters

• value - Scalar-or-collection container to validate and consume.

Returns

A V1 DTO preserving the input type and shape.

Errors

Returns ValueWireEncodeError::NonFiniteFloat for a non-finite float, ValueWireEncodeError::BigDecimalScaleTooLarge for a decimal whose exponent is outside V1’s supported range, or ValueWireEncodeError::InstantYearOutOfRange for an instant outside the supported UTC year range. With the json feature, returns JsonNumberNotRoundTrippable if a runtime JSON number in either the scalar or collection shape, including a nested number, cannot preserve its serde_json::Number identity under the V1 number model.