qubit-value 0.11.0

Type-safe containers for single, multi-valued, and named runtime values
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Closed mapping between protocol data types and value storage variants.

pub(crate) use std::collections::HashMap;
pub(crate) use std::time::Duration;

#[cfg(feature = "big-decimal")]
pub(crate) use bigdecimal::BigDecimal;
#[cfg(feature = "chrono")]
pub(crate) use chrono::DateTime;
#[cfg(feature = "chrono")]
pub(crate) use chrono::NaiveDate;
#[cfg(feature = "chrono")]
pub(crate) use chrono::NaiveDateTime;
#[cfg(feature = "chrono")]
pub(crate) use chrono::NaiveTime;
#[cfg(feature = "chrono")]
pub(crate) use chrono::Utc;
#[cfg(feature = "big-integer")]
pub(crate) use num_bigint::BigInt;
pub(crate) use qubit_datatype::DataType;
#[cfg(feature = "json")]
pub(crate) use serde_json::Value;
#[cfg(feature = "url")]
pub(crate) use url::Url;

/// Invokes a callback with the complete value type table.
///
/// Each row contains, in order: feature attributes, enum variant, Rust storage
/// type, [`qubit_datatype::DataType`], materialization strategy, natural JSON
/// class, [`qubit_datatype::NumberRef`] projection strategy, public variant
/// documentation for both containers, scalar wire attributes, collection wire
/// attributes, the stable V1 wire tag, and the Wire V1 preflight strategy.
///
/// The materialization strategy is consumed by generated owned accessors and
/// scalar projection code. `copy` dereferences borrowed storage, while `clone`
/// clones it.
macro_rules! for_each_value_type {
    ($macro:ident $(, $arg:expr)*) => {
        $macro! {
            $($arg),*;
            ([], Bool, bool, $crate::value_type_table::DataType::Bool, copy, json_bool, not_number, "Boolean value", "Boolean value list", [], [], "bool", boolean),
            ([], Char, char, $crate::value_type_table::DataType::Char, copy, json_string, not_number, "Character value", "Character value list", [], [], "char", borrowed_text),
            ([], Int8, i8, $crate::value_type_table::DataType::Int8, copy, json_number, number_copy, "8-bit signed integer", "8-bit signed integer list", [], [], "int8", json_integer),
            ([], Int16, i16, $crate::value_type_table::DataType::Int16, copy, json_number, number_copy, "16-bit signed integer", "16-bit signed integer list", [], [], "int16", json_integer),
            ([], Int32, i32, $crate::value_type_table::DataType::Int32, copy, json_number, number_copy, "32-bit signed integer", "32-bit signed integer list", [], [], "int32", json_integer),
            ([], Int64, i64, $crate::value_type_table::DataType::Int64, copy, json_number, number_copy, "64-bit signed integer", "64-bit signed integer list", [], [], "int64", json_integer),
            ([], Int128, i128, $crate::value_type_table::DataType::Int128, copy, json_string, number_copy, "128-bit signed integer", "128-bit signed integer list", [serde(with = "crate::wire::int128")], [serde(with = "crate::wire::int128_vec")], "int128", decimal_text),
            ([], UInt8, u8, $crate::value_type_table::DataType::UInt8, copy, json_number, number_copy, "8-bit unsigned integer", "8-bit unsigned integer list", [], [], "uint8", json_integer),
            ([], UInt16, u16, $crate::value_type_table::DataType::UInt16, copy, json_number, number_copy, "16-bit unsigned integer", "16-bit unsigned integer list", [], [], "uint16", json_integer),
            ([], UInt32, u32, $crate::value_type_table::DataType::UInt32, copy, json_number, number_copy, "32-bit unsigned integer", "32-bit unsigned integer list", [], [], "uint32", json_integer),
            ([], UInt64, u64, $crate::value_type_table::DataType::UInt64, copy, json_number, number_copy, "64-bit unsigned integer", "64-bit unsigned integer list", [], [], "uint64", json_integer),
            ([], UInt128, u128, $crate::value_type_table::DataType::UInt128, copy, json_string, number_copy, "128-bit unsigned integer", "128-bit unsigned integer list", [serde(with = "crate::wire::uint128")], [serde(with = "crate::wire::uint128_vec")], "uint128", decimal_text),
            ([], Float32, f32, $crate::value_type_table::DataType::Float32, copy, json_float32, number_copy, "32-bit floating-point number", "32-bit floating-point number list", [serde(with = "crate::wire::float32")], [serde(with = "crate::wire::float32_vec")], "float32", json_float),
            ([], Float64, f64, $crate::value_type_table::DataType::Float64, copy, json_float64, number_copy, "64-bit floating-point number", "64-bit floating-point number list", [serde(with = "crate::wire::float64")], [serde(with = "crate::wire::float64_vec")], "float64", json_float),
            ([cfg(feature = "big-integer")], BigInteger, $crate::value_type_table::BigInt, $crate::value_type_table::DataType::BigInteger, clone, json_string, number_ref, "Arbitrary-precision integer", "Arbitrary-precision integer list", [serde(with = "crate::wire::big_integer")], [serde(with = "crate::wire::big_integer_vec")], "biginteger", big_integer_text),
            ([cfg(feature = "big-decimal")], BigDecimal, $crate::value_type_table::BigDecimal, $crate::value_type_table::DataType::BigDecimal, clone, json_string, number_ref, "Arbitrary-precision decimal", "Arbitrary-precision decimal list", [serde(with = "crate::wire::big_decimal")], [serde(with = "crate::wire::big_decimal_vec")], "bigdecimal", decimal_object),
            ([], String, String, $crate::value_type_table::DataType::String, clone, json_string, not_number, "String value", "String value list", [], [], "string", borrowed_text),
            ([cfg(feature = "chrono")], Date, $crate::value_type_table::NaiveDate, $crate::value_type_table::DataType::Date, copy, json_string, not_number, "Calendar date", "Calendar date list", [serde(with = "crate::wire::date")], [serde(with = "crate::wire::date_vec")], "date", temporal_text),
            ([cfg(feature = "chrono")], Time, $crate::value_type_table::NaiveTime, $crate::value_type_table::DataType::Time, copy, json_string, not_number, "Time of day", "Time-of-day list", [serde(with = "crate::wire::time")], [serde(with = "crate::wire::time_vec")], "time", temporal_text),
            ([cfg(feature = "chrono")], DateTime, $crate::value_type_table::NaiveDateTime, $crate::value_type_table::DataType::DateTime, copy, json_string, not_number, "Date and time", "Date-and-time list", [serde(with = "crate::wire::datetime")], [serde(with = "crate::wire::datetime_vec")], "datetime", temporal_text),
            ([cfg(feature = "chrono")], Instant, $crate::value_type_table::DateTime<$crate::value_type_table::Utc>, $crate::value_type_table::DataType::Instant, copy, json_string, not_number, "UTC instant", "UTC instant list", [serde(with = "crate::wire::instant")], [serde(with = "crate::wire::instant_vec")], "instant", temporal_text),
            ([], Duration, $crate::value_type_table::Duration, $crate::value_type_table::DataType::Duration, copy, json_duration, not_number, "Duration", "Duration list", [serde(with = "crate::wire::duration")], [serde(with = "crate::wire::duration_vec")], "duration", duration_object),
            ([cfg(feature = "url")], Url, $crate::value_type_table::Url, $crate::value_type_table::DataType::Url, clone, json_string, not_number, "URL", "URL list", [serde(with = "crate::wire::url")], [serde(with = "crate::wire::url_vec")], "url", borrowed_text),
            ([], StringMap, $crate::value_type_table::HashMap<String, String>, $crate::value_type_table::DataType::StringMap, clone, json_object, not_number, "Map with string keys and values", "String-map list", [serde(with = "crate::wire::string_map")], [serde(with = "crate::wire::string_map_vec")], "stringmap", string_map),
            ([cfg(feature = "json")], Json, $crate::value_type_table::Value, $crate::value_type_table::DataType::Json, clone, json_identity, not_number, "JSON value", "JSON value list", [serde(with = "crate::wire::json")], [serde(with = "crate::wire::json_vec")], "json", json_tree),
        }
    };
}

/// Materializes an owned value from borrowed variant storage.
macro_rules! materialize_stored {
    (copy, $value:expr) => {
        *$value
    };
    (clone, $value:expr) => {
        $value.clone()
    };
}

/// Resolves the scalar enum storage type for a public value family.
macro_rules! value_storage_type {
    (Url, $type:ty) => {
        Box<$type>
    };
    ($variant:ident, $type:ty) => {
        $type
    };
}

/// Moves a public payload into its scalar enum storage representation.
macro_rules! value_storage_new {
    (Url, $value:expr) => {
        Box::new($value)
    };
    ($variant:ident, $value:expr) => {
        $value
    };
}

/// Borrows the public payload stored by a scalar enum variant.
macro_rules! value_storage_ref {
    (Url, $value:expr) => {
        $value.as_ref()
    };
    ($variant:ident, $value:expr) => {
        $value
    };
}

/// Projects a table row into the payload type used by a borrowed view.
macro_rules! value_view_payload_type {
    (Bool, $projection:ident, $lt:lifetime, $ty:ty) => { bool };
    (Char, $projection:ident, $lt:lifetime, $ty:ty) => { char };
    (String, $projection:ident, $lt:lifetime, $ty:ty) => { &$lt str };
    ($variant:ident, number_copy, $lt:lifetime, $ty:ty) => { $ty };
    ($variant:ident, $projection:ident, $lt:lifetime, $ty:ty) => { &$lt $ty };
}

/// Projects table storage into the corresponding borrowed-view payload.
macro_rules! value_view_payload {
    (Bool, $projection:ident, $value:expr) => {
        *$value
    };
    (Char, $projection:ident, $value:expr) => {
        *$value
    };
    (String, $projection:ident, $value:expr) => {
        $value.as_str()
    };
    ($variant:ident, number_copy, $value:expr) => {
        *$value
    };
    ($variant:ident, $projection:ident, $value:expr) => {
        $value
    };
}

/// Materializes an owned public payload from scalar enum storage.
macro_rules! materialize_value_storage {
    (Url, $materialization:ident, $value:expr) => {
        $value.as_ref().clone()
    };
    ($variant:ident, $materialization:ident, $value:expr) => {
        materialize_stored!($materialization, $value)
    };
}

/// Moves scalar enum storage into its public payload type.
macro_rules! move_value_storage {
    (Url, $value:expr) => {
        *$value
    };
    ($variant:ident, $value:expr) => {
        $value
    };
}

/// Moves scalar enum storage into a matching multi-value element.
macro_rules! value_storage_into_multi {
    (Url, $value:expr) => {
        *$value
    };
    ($variant:ident, $value:expr) => {
        $value
    };
}