qubit_validator/report/path_segment.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
9//! Segments of a safe validation path.
10
11use std::fmt::Debug;
12use std::fmt::Formatter;
13use std::fmt::Result;
14
15/// One location segment in a validation path.
16///
17/// Segments sort by variant in the order listed below, then by their field
18/// label or numeric index within a variant.
19///
20/// # Examples
21///
22/// ```
23/// use qubit_validator::PathSegment;
24///
25/// let field = PathSegment::Field("profile");
26/// assert_eq!(format!("{field:?}"), "Field(<redacted>)");
27/// ```
28#[derive(Clone, Eq, Hash, Ord, PartialEq, PartialOrd)]
29#[non_exhaustive]
30pub enum PathSegment {
31 /// A declared field name.
32 Field(
33 /// Program-supplied field label; debug formatting redacts it.
34 &'static str,
35 ),
36 /// A sequence element index.
37 Index(
38 /// Zero-based sequence index.
39 usize,
40 ),
41 /// An opaque map entry index.
42 MapEntry(
43 /// Opaque map-entry position, never the raw map key.
44 usize,
45 ),
46 /// The key side of a map entry.
47 MapKey,
48 /// The value side of a map entry.
49 MapValue,
50}
51
52impl Debug for PathSegment {
53 /// Formats structural path data while redacting field labels.
54 fn fmt(&self, formatter: &mut Formatter<'_>) -> Result {
55 match self {
56 Self::Field(_) => formatter.write_str("Field(<redacted>)"),
57 Self::Index(index) => formatter.debug_tuple("Index").field(index).finish(),
58 Self::MapEntry(index) => formatter.debug_tuple("MapEntry").field(index).finish(),
59 Self::MapKey => formatter.write_str("MapKey"),
60 Self::MapValue => formatter.write_str("MapValue"),
61 }
62 }
63}