qubit_argument/argument/
argument_error_kind.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//! Structured kinds of argument validation failure.
9
10use crate::argument::{
11    ArgumentValue,
12    ComparisonConstraint,
13    IndexRole,
14    LengthConstraint,
15    LengthMetric,
16    PatternExpectation,
17    RangeConstraint,
18};
19
20/// Identifies the validation rule that an argument failed.
21///
22/// Each variant stores only structured context needed to inspect and format
23/// the failure. Validated string contents are never captured implicitly.
24#[non_exhaustive]
25#[derive(Debug, Clone, PartialEq, Eq)]
26pub enum ArgumentErrorKind {
27    /// The required argument was absent.
28    Missing,
29    /// The string argument contained no non-whitespace characters.
30    Blank,
31    /// The collection argument was empty.
32    Empty,
33    /// The argument length did not satisfy a length constraint.
34    Length {
35        /// The observed length in the unit identified by `metric`.
36        actual: usize,
37        /// The required length relationship.
38        constraint: LengthConstraint,
39        /// The unit used to measure the observed and required lengths.
40        metric: LengthMetric,
41    },
42    /// A scalar argument did not satisfy a comparison constraint.
43    Comparison {
44        /// The observed numeric or duration value.
45        actual: ArgumentValue,
46        /// The required comparison relationship.
47        constraint: ComparisonConstraint,
48    },
49    /// The numeric argument was outside a required range.
50    Range {
51        /// The observed numeric value.
52        actual: ArgumentValue,
53        /// The required range.
54        constraint: RangeConstraint,
55    },
56    /// The supplied length constraint was internally invalid.
57    InvalidLengthConstraint {
58        /// The invalid length constraint.
59        constraint: LengthConstraint,
60        /// The unit to which the invalid constraint would have applied.
61        metric: LengthMetric,
62    },
63    /// The supplied numeric range was internally invalid.
64    InvalidRangeConstraint {
65        /// The invalid numeric range.
66        constraint: RangeConstraint,
67    },
68    /// The argument or numeric constraint contained a floating-point NaN value.
69    NotANumber,
70    /// The floating-point argument was positive or negative infinity.
71    NotFinite {
72        /// The rejected infinite floating-point value.
73        actual: ArgumentValue,
74    },
75    /// An element or position index was outside its valid domain.
76    Index {
77        /// The rejected index.
78        index: usize,
79        /// The collection size used for validation.
80        size: usize,
81        /// Whether the index identifies an element or a position.
82        role: IndexRole,
83    },
84    /// A position range was invalid for a collection size.
85    IndexRange {
86        /// The inclusive start position.
87        start: usize,
88        /// The exclusive end position.
89        end: usize,
90        /// The collection size used for validation.
91        size: usize,
92    },
93    /// An offset and length did not fit within a total length.
94    Bounds {
95        /// The rejected starting offset.
96        offset: usize,
97        /// The rejected span length.
98        length: usize,
99        /// The available total length.
100        total_length: usize,
101    },
102    /// A string did not satisfy a pattern expectation.
103    Pattern {
104        /// The pattern text used for validation.
105        pattern: String,
106        /// Whether a match or non-match was required.
107        expectation: PatternExpectation,
108    },
109    /// A caller-defined validation rule failed.
110    Custom {
111        /// A machine-readable caller-defined code.
112        code: String,
113        /// A human-readable caller-defined explanation.
114        message: String,
115    },
116}
qubit_argument/argument/argument_error_kind.rs

qubit_argument/argument/
argument_error_kind.rs
