Skip to main content

Crate qubit_value

Crate qubit_value 

Source
Expand description

§Value Processing Framework

Provides type-safe value storage and access functionality, supporting single values, collections, explicit scalar-or-collection shape, and named values.

§Public API Overview

§Core behavior

  • Value::get and MultiValues::get perform strict typed reads.
  • ValueContainer preserves whether the source supplied a scalar or an explicit collection, even when the collection contains one item.
  • to methods use qubit-datatype conversion policy and resource limits.
  • Optional type families and conversion methods are available only when the corresponding crate features are enabled; all-features documentation shows the superset of those APIs.
  • Value::is_unset and ValueContainer::is_unset indicate that no concrete value is stored.
  • MultiValues::is_unset distinguishes no collection from a concrete collection; MultiValues::is_empty reports only that its length is zero.
  • Generic set replaces a value infallibly; MultiValues::add remains fallible because appended values must have the same data type.
  • Serde uses the strict, type-preserving ValueWireV1 envelope. Its canonical JSON representation is byte-stable for the same value under the supported serde_json version and configuration. String-map keys and nested JSON object keys are emitted in lexicographic order. Other Serde formats are supported as representations, but are outside this byte-level stability contract. With the natural-json feature, to_json_value provides a separate natural JSON projection with the same ordering.
  • Version one rejects externally tagged representations.
  • Non-finite floats may exist in memory, but V1 Serde and natural JSON reject them because JSON has no NaN or infinity number literals.
  • JSON numbers follow qubit-json’s explicit range contract: negative integers fit i64, non-negative integers fit u64, and fractional or exponential values are finite f64. Wider exact values use the crate’s explicit string-based integer and decimal wire representations.

§Usage Examples

§Single Value Operations

use qubit_value::Value;

// Create and access a single value
let value = Value::Int32(42);
assert_eq!(value.get_int32().unwrap(), 42);

// Strict generic access
let number: i32 = value.get().unwrap();
assert_eq!(number, 42);

§Multiple Values Operations

use qubit_value::MultiValues;

// Create and access multiple values
let mut values = MultiValues::Int32(vec![1, 2, 3]);
assert_eq!(values.len(), 3);

// Add values
values.add(4).unwrap();
assert_eq!(values.get_int32s().unwrap(), &[1, 2, 3, 4]);

§Named Value Operations

use qubit_value::{NamedValue, Value};

// Create a named value
let config = NamedValue::new("port", Value::Int32(8080));
assert_eq!(config.name(), "port");
assert_eq!(config.value().get_int32().unwrap(), 8080);

§Explicit Shape Operations

use qubit_value::ValueContainer;

let scalar = ValueContainer::from(42_i32);
let collection = ValueContainer::from(vec![42_i32]);
assert!(scalar.is_scalar());
assert!(collection.is_collection());

Structs§

MultiValues
Multiple typed runtime values with private storage representation.
NamedMultiValues
Named multiple values
NamedValue
Named single value
Value
Single typed runtime value with private storage representation.
ValueMissing
Describes the storage state, requested type and source of a missing read.
ValueWireEncodePreflight
Performs conservative resource checks before Wire V1 sorting and formatting.
ValueWirePayloadRefV1
Borrowed unversioned V1 payload for serialization without cloning.
ValueWirePayloadV1
Typed V1 scalar-or-collection payload without an enclosing version field.
ValueWirePayloadV1Seed
Explicit Serde seed for decoding one unversioned V1 payload.
ValueWireRefV1
Borrowed standalone V1 envelope for serialization without cloning.
ValueWireV1
Stable version-one wire DTO for a scalar or homogeneous collection.
ValueWireV1Seed
Explicit Serde seed for decoding one V1 envelope.

Enums§

MultiValuesRef
Borrowed semantic view preserving source types without owning payloads.
NumericComparisonError
Describes why two crate::Value instances cannot be numerically ordered.
ValueContainer
A typed value whose scalar or collection shape is explicit.
ValueError
Value processing error type
ValueMissingReason
Identifies why a read could not produce a concrete value.
ValueRef
Borrowed semantic view preserving source types without owning payloads.
ValueWireDecodeError
Error produced by a bounded crate::ValueWireV1 JSON decoder.
ValueWireEncodeError
A runtime value cannot be represented by the JSON V1 wire contract.

Traits§

IntoValueDefault
Converts ergonomic default arguments into the value type expected by a read API.
StrictValueRead
Marks target types supported by exact, non-converting reads.

Type Aliases§

ValueResult
Result returned by value processing operations.