qubit_value/value_missing_reason.rs
1// =============================================================================
2// Copyright (c) 2025 - 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Classification independent of the source and requested value types.
9
10/// Identifies why a read could not produce a concrete value.
11///
12/// The reason is independent of the source and target types. Inspect the
13/// accompanying [`crate::ValueMissing`] accessors for those types and for a
14/// collection index when one is available.
15///
16/// # Examples
17///
18/// ```
19/// use qubit_datatype::DataType;
20/// use qubit_value::Value;
21/// use qubit_value::ValueMissingReason;
22///
23/// let error = Value::new_unset(DataType::Int32)
24/// .get::<i32>()
25/// .unwrap_err();
26/// assert_eq!(error.missing().unwrap().reason(), ValueMissingReason::UnsetScalar);
27/// ```
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
29#[non_exhaustive]
30pub enum ValueMissingReason {
31 /// Scalar storage is unset with a declared type.
32 UnsetScalar,
33 /// Collection storage is unset with a declared element type.
34 UnsetCollection,
35 /// A concrete collection has no first item.
36 EmptyCollection,
37 /// Conversion policy classified a concrete scalar or collection item as
38 /// missing.
39 Conversion,
40}