qubit_budget/resource/limit/
observation.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Describes whether a reported resource measurement is exact or conservative.
9// qubit-style: allow source-test-pair
10
11use std::fmt::Debug;
12use std::fmt::Display;
13use std::fmt::Formatter;
14use std::fmt::Result as FmtResult;
15
16/// A resource observation that may be exact or only a safe lower bound.
17///
18/// # Type Parameters
19///
20/// * `Q` - Exact unsigned quantity used for measurements and accounting.
21///
22/// # Examples
23///
24/// ```
25/// use qubit_budget::Observation;
26///
27/// let observation = Observation::AtLeast(4_u64);
28/// assert_eq!(observation.exact(), None);
29/// assert_eq!(observation.lower_bound(), 4);
30/// ```
31#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
32pub enum Observation<Q> {
33    /// The measured quantity is exact.
34    Exact(
35        /// Exact observed quantity.
36        Q,
37    ),
38
39    /// The measured quantity is at least the contained lower bound.
40    AtLeast(
41        /// Proven lower bound for the observed quantity.
42        Q,
43    ),
44}
45
46impl<Q> Display for Observation<Q>
47where
48    Q: Display,
49{
50    /// Formats the observation with its precision qualifier.
51    ///
52    /// # Parameters
53    ///
54    /// * `formatter` - Formatter receiving the textual representation.
55    ///
56    /// # Returns
57    ///
58    /// Formats the observation with its precision qualifier.
59    ///
60    /// # Errors
61    ///
62    /// Returns [`std::fmt::Error`] when the formatter rejects the output.
63    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
64        match self {
65            Self::Exact(value) => write!(formatter, "exactly {value}"),
66            Self::AtLeast(value) => write!(formatter, "at least {value}"),
67        }
68    }
69}
70
71impl<Q> Observation<Q>
72where
73    Q: Copy + Debug,
74{
75    /// Returns the exact quantity, or `None` for a lower-bound observation.
76    ///
77    /// # Returns
78    ///
79    /// Returns the exact quantity, or `None` for a lower-bound observation.
80    #[inline(always)]
81    #[must_use]
82    pub const fn exact(self) -> Option<Q> {
83        match self {
84            Self::Exact(value) => Some(value),
85            Self::AtLeast(_) => None,
86        }
87    }
88
89    /// Returns the safe lower bound represented by this observation.
90    ///
91    /// # Returns
92    ///
93    /// Returns the safe lower bound represented by this observation.
94    #[inline(always)]
95    #[must_use]
96    pub const fn lower_bound(self) -> Q {
97        match self {
98            Self::Exact(value) | Self::AtLeast(value) => value,
99        }
100    }
101}
qubit_budget/resource/limit/observation.rs

qubit_budget/resource/limit/
observation.rs
