qubit-argument 0.4.7

Structured, ownership-preserving argument validation for Rust applications
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

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Primitive numeric values supported by numeric validation.

use crate::argument::ArgumentValue;
use crate::argument::internal::Sealed;

/// Restricts numeric validation to supported primitive numeric values.
///
/// Implementations provide the type's zero value, an exact structured error
/// representation, and NaN detection. The trait is private so arbitrary
/// partially ordered caller types cannot opt into numeric validation.
pub(in crate::argument) trait NumericValue: Sealed + Copy + PartialOrd {
    /// Returns the zero value for this primitive numeric type.
    ///
    /// # Returns
    ///
    /// The type's zero value.
    #[must_use]
    fn zero() -> Self;

    /// Captures this value without losing integer magnitude or floating bits.
    ///
    /// # Returns
    ///
    /// The exact structured representation of this value.
    fn to_argument_value(self) -> ArgumentValue;

    /// Returns whether this value is a floating-point NaN.
    ///
    /// Integer implementations always return `false`.
    ///
    /// # Returns
    ///
    /// `true` for a floating-point NaN; otherwise, `false`.
    #[must_use]
    fn is_nan(self) -> bool;
}

/// Implements primitive numeric conversion and non-NaN behavior for integers.
macro_rules! impl_numeric_value_for_integer {
    ($($numeric_type:ty),+ $(,)?) => {
        $(
            impl NumericValue for $numeric_type {
                /// Returns integer zero.
                ///
                /// # Returns
                ///
                /// Zero of this integer type.
                #[inline]
                fn zero() -> Self {
                    0
                }

                /// Captures the integer without losing its value.
                ///
                /// # Returns
                ///
                /// The exact structured integer value.
                #[inline]
                fn to_argument_value(self) -> ArgumentValue {
                    ArgumentValue::from(self)
                }

                /// Reports that an integer can never be NaN.
                ///
                /// # Returns
                ///
                /// Always `false`.
                #[inline]
                fn is_nan(self) -> bool {
                    false
                }
            }
        )+
    };
}

impl_numeric_value_for_integer!(i8, i16, i32, i64, i128, isize);
impl_numeric_value_for_integer!(u8, u16, u32, u64, u128, usize);

impl NumericValue for f32 {
    /// Returns positive floating-point zero.
    ///
    /// # Returns
    ///
    /// Positive `f32` zero.
    #[inline]
    fn zero() -> Self {
        0.0
    }

    /// Captures the exact IEEE 754 bit pattern of this value.
    ///
    /// # Returns
    ///
    /// The exact structured floating-point value.
    #[inline]
    fn to_argument_value(self) -> ArgumentValue {
        ArgumentValue::from(self)
    }

    /// Returns whether this value is NaN.
    ///
    /// # Returns
    ///
    /// `true` when this value is NaN; otherwise, `false`.
    #[inline]
    fn is_nan(self) -> bool {
        self.is_nan()
    }
}

impl NumericValue for f64 {
    /// Returns positive floating-point zero.
    ///
    /// # Returns
    ///
    /// Positive `f64` zero.
    #[inline]
    fn zero() -> Self {
        0.0
    }

    /// Captures the exact IEEE 754 bit pattern of this value.
    ///
    /// # Returns
    ///
    /// The exact structured floating-point value.
    #[inline]
    fn to_argument_value(self) -> ArgumentValue {
        ArgumentValue::from(self)
    }

    /// Returns whether this value is NaN.
    ///
    /// # Returns
    ///
    /// `true` when this value is NaN; otherwise, `false`.
    #[inline]
    fn is_nan(self) -> bool {
        self.is_nan()
    }
}