qubit-value

A type-safe value container framework built on qubit_datatype::DataType, providing unified abstractions for single values, multi-values, and named values with generic construction/access/mutation, type conversion, and complete serde serialization support.

Overview

Qubit Value provides a comprehensive solution for handling dynamically-typed values in a type-safe manner. It bridges the gap between static typing and runtime flexibility, offering powerful abstractions for value storage, retrieval, and conversion while maintaining Rust's safety guarantees.

Configuration Object Support: If you need configuration objects based on

different types of multi-value designs, consider using the

qubit-config crate, which provides

comprehensive configuration management functionality. You can find more

information on GitHub and

crates.io.

Features

🎯 Core Design

• Enum-Based Architecture: Uses Value/MultiValues enums to represent all

supported data types

• Type Safety: Enum variants carry static types; failures are expressed

through Result<T, ValueError>

• Zero-Cost Abstractions: Basic types are stored directly; extensive use of

reference returns to avoid unnecessary copies

• Named Values: NamedValue/NamedMultiValues provide name binding for

configuration/identification scenarios

• Serde Support: All core types implement Serialize/Deserialize
• Ergonomic Defaults: get_or, to_or, and list-default APIs accept

scalar defaults, borrowed string literals, arrays, slices, vectors, and borrowed vectors

• Flexible Collection Inputs: MultiValues::new/set/add accept direct

arrays, slices, vectors, borrowed vectors, and borrowed string collections

• Big Number Support: Full support for BigInt and BigDecimal for

high-precision calculations

• Extended Types: Native support for isize/usize, Duration, Url,

HashMap<String, String>, and serde_json::Value

📦 Core Types

• Value: Single value container with Empty(DataType) and 28 variants

covering primitives, strings, date-time, big numbers, platform integers, duration, URL, string maps, and JSON

• MultiValues: Multi-value container corresponding to Vec<T> enum

variants, with Empty(DataType)

• NamedValue: Name-bound Value providing Deref/DerefMut access to

inner value

• NamedMultiValues: Name-bound MultiValues with Deref/DerefMut and

to_named_value() conversion

• ValueError & ValueResult<T>: Standard error type and result alias

Installation

Add this to your Cargo.toml:

[dependencies]
qubit-value = "0.7"

Usage Examples

Single Value Operations

use qubit_value::{Value, ValueError};
use qubit_datatype::DataType;
use num_bigint::BigInt;
use bigdecimal::BigDecimal;
use std::str::FromStr;

// Generic construction and type-inferred retrieval
let v = Value::new(8080i32);
let port: i32 = v.get()?;  // Type inference from variable
assert_eq!(port, 8080);

// Named getter (returns Copy or reference)
assert_eq!(v.get_int32()?, 8080);

// Type inference in function parameters
fn check_port(p: i32) -> bool { p > 1024 }
assert!(check_port(v.get()?));  // Inferred as i32 from function signature

// Cross-type conversion via to<T>()
assert_eq!(v.to::<i64>()?, 8080i64);
assert_eq!(v.to::<String>()?, "8080".to_string());

// Big number with type inference
let big_int = Value::new(BigInt::from(12345678901234567890i64));
let num: BigInt = big_int.get()?;  // Type inference

// Empty value and type management
let mut any = Value::Int32(42);
any.clear();
assert!(any.is_empty());
assert_eq!(any.data_type(), DataType::Int32);
any.set_type(DataType::String);
any.set("hello")?;
assert_eq!(any.get_string()?, "hello");

Extended Types

use qubit_value::Value;
use std::time::Duration;
use url::Url;
use std::collections::HashMap;

// Duration
let v = Value::new(Duration::from_secs(30));
let d: Duration = v.get()?;
assert_eq!(d, Duration::from_secs(30));
// Default String conversion uses milliseconds.
let s: String = v.to()?;
assert_eq!(s, "30000ms");
let v2 = Value::String("30s".to_string());
let d2: Duration = v2.to()?;
assert_eq!(d2, Duration::from_secs(30));

// Url
let url = Url::parse("https://example.com").unwrap();
let v = Value::new(url.clone());
let got: Url = v.get()?;
assert_eq!(got, url);
// Parse from string
let v2 = Value::String("https://example.com".to_string());
let got2: Url = v2.to()?;
assert_eq!(got2, url);

// HashMap<String, String>
let mut map = HashMap::new();
map.insert("host".to_string(), "localhost".to_string());
let v = Value::new(map.clone());
let got: HashMap<String, String> = v.get()?;
assert_eq!(got, map);

// JSON escape hatch
let j = serde_json::json!({"key": "value"});
let v = Value::from_json_value(j.clone());
let got: serde_json::Value = v.get()?;
assert_eq!(got, j);

// Serialize any type to JSON
#[derive(serde::Serialize, serde::Deserialize)]
struct Config { host: String, port: u16 }
let cfg = Config { host: "localhost".to_string(), port: 8080 };
let v = Value::from_serializable(&cfg)?;
let restored: Config = v.deserialize_json()?;

Multi-Value Operations

use qubit_value::{MultiValues, ValueError};
use qubit_datatype::DataType;

// Generic construction from a Vec<T>
let mut ports = MultiValues::new(vec![8080i32, 8081, 8082]);
assert_eq!(ports.count(), 3);
assert_eq!(ports.get_int32s()?, &[8080, 8081, 8082]);

// Direct arrays, slices, vectors, and borrowed vectors are accepted
let array_ports = MultiValues::new([8080i32, 8081, 8082]);
let more_ports = [9000i32, 9001];
let borrowed = MultiValues::new(more_ports.as_slice());
let owned = vec![7000i32, 7001];
let borrowed_vec = MultiValues::new(&owned);

// String lists can be built directly from &str collections
let servers = MultiValues::new(["api", "worker", "cache"]);
assert_eq!(servers.get_strings()?, &["api", "worker", "cache"]);

// Generic retrieval with type inference (clones Vec)
let nums: Vec<i32> = ports.get()?;

// Get first element
let first: i32 = ports.get_first()?;
assert_eq!(first, 8080);

// Generic add: single / Vec / slice
ports.add(8083)?;
ports.add(vec![8084, 8085])?;
ports.add(&[8086, 8087][..])?;
ports.add([8088, 8089])?;

// Generic set: replaces entire list
ports.set(vec![9001, 9002])?;
ports.set([9100, 9101])?;
ports.set(&owned)?;
assert_eq!(ports.get_int32s()?, &[7000, 7001]);

// Merge (types must match)
let mut a = MultiValues::Int32(vec![1, 2]);
let b = MultiValues::Int32(vec![3, 4]);
a.merge(&b)?;
assert_eq!(a.get_int32s()?, &[1, 2, 3, 4]);

// Convert to single value (takes first element)
let single = a.to_value();
let first_val: i32 = single.get()?;
assert_eq!(first_val, 1);

Defaulted Reads and Conversions

Defaulted APIs use the fallback only when the value is empty or the list has no items. Type mismatches and failed conversions still return errors.

use qubit_datatype::DataType;
use qubit_value::{MultiValues, Value};

// Strict reads with defaults
let value = Value::Empty(DataType::String);
let host: String = value.get_or("localhost")?;
assert_eq!(host, "localhost");

let value = Value::String("8080".to_string());
let port: u16 = value.to_or(9000u16)?;
assert_eq!(port, 8080);

// Multi-value strict reads with collection defaults
let values = MultiValues::Empty(DataType::String);
let paths: Vec<String> = values.get_or(["cache", "tmp"])?;
assert_eq!(paths, vec!["cache".to_string(), "tmp".to_string()]);

// First-value conversion with a scalar default
let values = MultiValues::Empty(DataType::UInt16);
let port: u16 = values.to_or(8080u16)?;
assert_eq!(port, 8080);

// List conversion with array or slice defaults
let values = MultiValues::Empty(DataType::String);
let tags: Vec<String> = values.to_list_or(["blue", "green"])?;
assert_eq!(tags, vec!["blue".to_string(), "green".to_string()]);

Collection Argument Forms

The collection-style APIs accept the convenient forms you normally have at the call site. This applies to MultiValues::new, MultiValues::set, MultiValues::add, and defaulted list reads such as get_or and to_list_or.

use qubit_datatype::DataType;
use qubit_value::MultiValues;

let array_values = MultiValues::new([1i32, 2, 3]);
let slice_source = [4i32, 5, 6];
let slice_values = MultiValues::new(slice_source.as_slice());
let vec_source = vec![7i32, 8, 9];
let vec_values = MultiValues::new(vec_source.clone());
let borrowed_vec_values = MultiValues::new(&vec_source);

let mut values = MultiValues::Empty(DataType::Int32);
values.set([10, 11, 12])?;
values.add(slice_source.as_slice())?;
values.add(&vec_source)?;

let strings = MultiValues::new(["api", "worker"]);
let fallback: Vec<String> = MultiValues::Empty(DataType::String)
    .get_or(["cache", "tmp"])?;

Named Value Operations

use qubit_value::{NamedValue, NamedMultiValues, Value, MultiValues};

// Named single value
let mut nv = NamedValue::new("timeout", Value::new(30i32));
assert_eq!(nv.name(), "timeout");
let timeout: i32 = nv.get()?;
assert_eq!(timeout, 30);

nv.set_name("read_timeout");
nv.set(45i32)?;
assert_eq!(nv.get_int32()?, 45);

// Named multi-value
let mut nmv = NamedMultiValues::new("ports", MultiValues::new(vec![8080i32, 8081]));
nmv.add(8082)?;
let first_port: i32 = nmv.get_first()?;
assert_eq!(first_port, 8080);

// Named multi-value → Named single value (takes first element)
let first_named = nmv.to_named_value();
assert_eq!(first_named.name(), "ports");
let val: i32 = first_named.get()?;
assert_eq!(val, 8080);

API Reference

Generic API

Construction

• Single Value: Value::new<T>(t) -> Value
• Multi-Value: MultiValues::new<S>(values) -> MultiValues

MultiValues::new accepts Vec<T>, &Vec<T>, &[T], [T; N], and &[T; N]. For string values it also accepts Vec<&str>, &Vec<&str>, &[&str], [&str; N], and &[&str; N], producing Vec<String> internally.

Supported T for new: bool, char, i8, i16, i32, i64, i128, u8, u16, u32, u64, u128, f32, f64, String, &str, NaiveDate, NaiveTime, NaiveDateTime, DateTime<Utc>, BigInt, BigDecimal, isize, usize, Duration, Url, HashMap<String, String>, serde_json::Value.

Retrieval

• Single Value: Value::get<T>(&self) -> ValueResult<T>
• Single Value with Default: Value::get_or<T>(&self, default) -> ValueResult<T>
• Multi-Value: MultiValues::get<T>(&self) -> ValueResult<Vec<T>>
• Multi-Value with Default: MultiValues::get_or<T>(&self, default) -> ValueResult<Vec<T>>
• First Element: MultiValues::get_first<T>(&self) -> ValueResult<T>
• First Element with Default: MultiValues::get_first_or<T>(&self, default) -> ValueResult<T>

get<T>() performs strict type matching — the stored variant must be exactly T. For cross-type conversion use to<T>() instead.

Mutation

• Single Value: Value::set<T>(&mut self, t) -> ValueResult<()>
• Multi-Value:
• MultiValues::set<T, S>(&mut self, values: S) -> ValueResult<()> where

S can be T, Vec<T>, &Vec<T>, &[T], [T; N], or &[T; N]

• MultiValues::add<T, S>(&mut self, values: S) supports T, Vec<T>,

&Vec<T>, &[T], [T; N], or &[T; N]

• String collections also accept Vec<&str>, &Vec<&str>, &[&str],

[&str; N], and &[&str; N]

Type Conversion

• Value::to<T>(&self) -> ValueResult<T> — converts to T according to

the shared conversion rules. Supports cross-type conversion with range checking where applicable.

• Value::to_or<T>(&self, default) -> ValueResult<T> — converts to T,

or returns the default when the value is empty.

• Value::to_or_with<T>(&self, default, options) -> ValueResult<T> —

same fallback behavior while using explicit conversion options.

• MultiValues::to<T>(&self) -> ValueResult<T> — converts the first stored

value.

• MultiValues::to_or<T>(&self, default) -> ValueResult<T> — converts the

first stored value, or returns the default when no value exists.

• MultiValues::to_or_with<T>(&self, default, options) -> ValueResult<T> —

same fallback behavior while using explicit conversion options.

• MultiValues::to_list<T>(&self) -> ValueResult<Vec<T>> — converts all

stored values.

• MultiValues::to_list_with<T>(&self, options) -> ValueResult<Vec<T>> —

converts all stored values with explicit conversion options.

• MultiValues::to_list_or<T>(&self, default) -> ValueResult<Vec<T>> —

converts all stored values, or returns the default when the result is empty.

• MultiValues::to_list_or_with<T>(&self, default, options) -> ValueResult<Vec<T>> —

same list fallback behavior while using explicit conversion options.

Supported target types and their accepted source variants:

Named API

Single Value

• Getters: get_xxx() methods — get_bool(), get_int32(),

get_string(), get_duration(), get_url(), get_string_map(), get_json(), etc.

• Setters: set_xxx() methods — set_bool(), set_int32(),

set_string(), set_duration(), set_url(), set_string_map(), set_json(), etc.

Multi-Value

• Getters: get_xxxs() — get_int32s(), get_strings(),

get_durations(), get_urls(), get_string_maps(), get_jsons(), etc.

• Setters: set_xxxs() — set_int32s(), set_strings(), etc.
• Adders: add_xxx() — add_int32(), add_string(), add_duration(),

add_url(), etc.

• Slice Operations: *_slice variants — set_int32s_slice(),

add_strings_slice(), etc.

JSON Utilities (on Value)

• Value::from_json_value(serde_json::Value) -> Value
• Value::from_serializable<T: Serialize>(value: &T) -> ValueResult<Value>
• Value::deserialize_json<T: DeserializeOwned>(&self) -> ValueResult<T>

Utility Methods

Single Value

• data_type() — get the data type
• is_empty() — check if empty
• clear() — clear the value (preserves type)
• set_type() — change the type

Multi-Value

• count() — get element count
• is_empty() — check if empty
• clear() — clear all values (preserves type)
• set_type() — change the type
• merge() — merge with another multi-value (types must match)
• to_value() — convert to single value (takes first element)

Error Types

use qubit_value::{ValueError, ValueResult};
use qubit_datatype::DataType;

// Main error variants
ValueError::NoValue                          // Empty value accessed
ValueError::TypeMismatch { expected, actual }// get<T>() type mismatch
ValueError::ConversionFailed { from, to }    // to<T>() unsupported direction
ValueError::ConversionError(String)          // to<T>() range/parse failure
ValueError::IndexOutOfBounds { index, len }  // multi-value index error
ValueError::JsonSerializationError(String)   // JSON serialization failure
ValueError::JsonDeserializationError(String) // JSON deserialization failure

All operations that may fail return ValueResult<T> = Result<T, ValueError>.

Supported Data Types

Basic Scalar Types

• Signed integers: i8, i16, i32, i64, i128
• Unsigned integers: u8, u16, u32, u64, u128
• Platform integers: isize, usize
• Floats: f32, f64
• Other: bool, char

String

• String (stored directly)

Date/Time Types

• NaiveDate, NaiveTime, NaiveDateTime, DateTime<Utc> (via chrono)

Big Number Types

• BigInt, BigDecimal (via num-bigint and bigdecimal)

Extended Types

• isize / usize: Platform-dependent integers
• Duration: std::time::Duration; string conversion uses the

configured duration unit, defaulting to milliseconds such as 1500ms. Parsing accepts ns, us, ms, s, m, h, and d suffixes; strings without a suffix are interpreted using the configured duration unit.

• Url: url::Url; string representation is the URL text
• HashMap<String, String>: String map; string representation is JSON
• serde_json::Value: JSON escape hatch for complex/custom types

Serialization Support

All types implement Serialize/Deserialize:

• Value, MultiValues, NamedValue, NamedMultiValues

Full type information is preserved during serialization and validated during deserialization.

Performance Notes

• Reference Returns: get_string() returns &str to avoid cloning
• Borrow Support: Value::new() and set() accept &str (converted to

String)

• Flexible Inputs: MultiValues::new/set/add accept direct arrays, slices,

vectors, and borrowed vectors for supported element types

• Borrowed Defaults: Defaulted reads can use borrowed string literals and

borrowed collection values without forcing callers to allocate first

Dependencies

[dependencies]
qubit-datatype = "0.2"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
thiserror = "2.0"
chrono = { version = "0.4", features = ["serde"] }
url = { version = "2.5", features = ["serde"] }
num-bigint = { version = "0.4", features = ["serde"] }
bigdecimal = { version = "0.4", features = ["serde"] }

Testing

This project maintains comprehensive test coverage with detailed validation of all functionality. Run ./ci-check.sh before publishing or committing changes.

License

Copyright (c) 2025 - 2026 Haixing Hu, Qubit Co. Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE for the full license text.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Haixing Hu - Qubit Co. Ltd.

---

For more information about Qubit open source projects, visit our GitHub organization.