qubit-value 0.12.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

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

//! Private storage representation for `Value`.

use qubit_datatype::DataType;

/// Defines the private storage representation for the public single-value
/// container from the shared value-type table.
macro_rules! define_value_enum {
    (
        ;
        $(
            (
                [$($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)*
            )
        ),+ $(,)?
    ) => {
        /// Internal single-value representation.
        ///
        /// Uses an enum to represent different types of values, providing
        /// type-safe value storage and access.
        ///
        /// This representation is private; downstream code uses [`crate::Value`]
        /// constructors and [`crate::ValueRef`] semantic views instead of matching
        /// storage details.
        ///
        /// # Behavior
        ///
        /// - Stores one value from the closed [`DataType`] family.
        /// - Provides strict getters and, with `converter`, option-controlled
        ///   conversion methods.
        /// - Distinguishes an unset container from concrete inner values.
        /// - The URL variant uses boxed storage internally to keep the enum
        ///   compact; use [`crate::Value::new`] and typed getters instead of relying
        ///   on the storage representation of individual variants.
        ///
        /// # Equality and hashing
        ///
        /// Equality preserves enum-variant identity. Signed zero is canonicalized,
        /// every NaN payload within one float width is equal, and unordered payloads
        /// hash structurally. Standard hash output is suitable for in-memory keys but
        /// is not a stable persistent fingerprint.
        ///
        /// # Examples
        ///
        /// ```rust
        /// use qubit_value::Value;
        ///
        /// let value = Value::Int32(42);
        /// assert_eq!(value.get_int32().unwrap(), 42);
        ///
        /// let number: i32 = value.get().unwrap();
        /// assert_eq!(number, 42);
        ///
        /// let text = Value::String("hello".to_string());
        /// assert_eq!(text.get_string().unwrap(), "hello");
        /// ```
        #[derive(Debug, Clone)]
        pub(crate) enum ValueRepr {
            /// Unset value with a declared data type.
            Unset(
                /// Declared data type retained while the value is unset.
                DataType,
            ),
            $(
                #[doc = $value_doc]
                $(#[$cfg])*
                $variant(
                    #[doc = concat!("Stored ", $value_doc, " payload.")]
                    value_storage_type!($variant, $type),
                ),
            )+
        }
    };
}

for_each_value_type!(define_value_enum);