qubit_argument/argument/constraint/length_metric.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//! Measurement units used by length validation.
9
10/// Identifies how an observed string or collection length was measured.
11///
12/// The metric is retained in structured errors so equal numeric lengths and
13/// constraints remain distinguishable across strings and collections.
14/// This enum is non-exhaustive; downstream matches must include a wildcard arm.
15///
16/// ```compile_fail
17/// use qubit_argument::LengthMetric;
18///
19/// fn label(metric: LengthMetric) -> &'static str {
20/// match metric {
21/// LengthMetric::Bytes => "bytes",
22/// LengthMetric::UnicodeScalars => "Unicode scalars",
23/// LengthMetric::Elements => "elements",
24/// }
25/// }
26/// ```
27///
28/// ```compile_fail
29/// #![deny(unused_must_use)]
30/// use qubit_argument::LengthMetric;
31///
32/// LengthMetric::Bytes;
33/// ```
34#[non_exhaustive]
35#[must_use]
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub enum LengthMetric {
38 /// The number of bytes in a UTF-8 string.
39 Bytes,
40 /// The number of Unicode scalar values in a string.
41 UnicodeScalars,
42 /// The number of elements in a collection.
43 Elements,
44}