qubit-value 0.13.1

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

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Admitted scalar projection and borrowed payload materialization.

use serde_json::Map;
use serde_json::Number;
use serde_json::Value as JsonValue;

use crate::ValueRef;

/// One admitted scalar; formatting results are moved into the output.
///
/// # Type Parameters
///
/// - `'a`: lifetime of source storage retained by a borrowed payload.
pub(in crate::json) enum PreparedScalar<'a> {
    /// Primitive or borrowed storage requiring no formatting cache.
    Borrowed(
        /// Source view whose family supports direct JSON materialization.
        ValueRef<'a>,
    ),
    /// Text already rendered within the projection budget.
    Formatted(
        /// Owned rendering moved into the output without formatting again.
        String,
    ),
    /// Floating-point number prepared with the required natural precision.
    Number(
        /// Admitted JSON number moved into the output without conversion.
        Number,
    ),
}

/// Materializes only the families admitted as borrowing their original storage.
macro_rules! borrowed_payload {
    (String, $class:ident, $value:expr) => {
        JsonValue::String($value.to_owned())
    };
    ($variant:ident, json_bool, $value:expr) => {
        JsonValue::Bool($value)
    };
    ($variant:ident, json_number, $value:expr) => {
        JsonValue::from($value)
    };
    ($variant:ident, json_identity, $value:expr) => {
        crate::wire::json::canonicalize_json_value($value)
    };
    ($variant:ident, json_object, $value:expr) => {{
        // Sorting borrowed entries before insertion avoids a measured
        // `preserve_order` regression from sorting the populated map.
        let mut entries: Vec<_> = $value.iter().collect();
        entries.sort_unstable_by(|(left, _), (right, _)| left.cmp(right));
        let mut object = Map::with_capacity(entries.len());
        for (key, value) in entries {
            object.insert(key.clone(), JsonValue::String(value.clone()));
        }
        JsonValue::Object(object)
    }};
    ($variant:ident, $class:ident, $value:expr) => {{
        let _ = $value;
        unreachable!("formatted payloads must use their prepared rendering")
    }};
}

/// Uses the closed type table for borrowed scalar materialization.
macro_rules! borrowed_match {
    ($value:expr; $(([$($cfg:meta),*], $variant:ident, $type:ty, $data_type:expr, $materialization:ident, $json_class:ident, $number_projection:ident, $value_doc:literal, $multi_doc:literal $(, $_wire:tt)*)),+ $(,)?) => {
        match $value {
            ValueRef::Unset(_) => JsonValue::Null,
            $($(#[$cfg])* ValueRef::$variant(value) => borrowed_payload!($variant, $json_class, value),)+
        }
    };
}

impl PreparedScalar<'_> {
    /// Produces the final JSON scalar; cached text and numbers are moved, not
    /// re-rendered.
    ///
    /// # Returns
    ///
    /// The owned JSON value represented by this admitted scalar.
    ///
    /// # Panics
    ///
    /// Panics if a borrowed payload requires formatting, violating the
    /// preparation invariant.
    #[must_use]
    pub(in crate::json) fn materialize(self) -> JsonValue {
        match self {
            Self::Borrowed(value) => for_each_value_type!(borrowed_match, value),
            Self::Formatted(text) => JsonValue::String(text),
            Self::Number(number) => JsonValue::Number(number),
        }
    }
}