qubit_json/decode/json_path_segment.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//! Typed location within a JSON document.
9
10/// Identifies an object key or array index in a JSON value path.
11///
12/// # Examples
13///
14/// ```
15/// use qubit_json::decode::{JsonDecoder, JsonNumberPolicy, JsonPathSegment, JsonValidatedDecodeOptions};
16/// use std::convert::Infallible;
17///
18/// let options = JsonValidatedDecodeOptions::builder().build();
19/// let mut saw_id = false;
20/// let result = JsonDecoder::unlimited().decode_unique_validated_str(
21/// r#"{"id":42}"#,
22/// &options,
23/// |path, _token| {
24/// saw_id = path == [JsonPathSegment::Key("id".to_owned())];
25/// Ok::<_, Infallible>(JsonNumberPolicy::Preserve)
26/// },
27/// )?;
28/// assert!(saw_id);
29/// assert_eq!(result.as_value()["id"].as_i64(), Some(42));
30/// # Ok::<(), Box<dyn std::error::Error>>(())
31/// ```
32#[non_exhaustive]
33#[derive(Debug, Clone, PartialEq, Eq, Hash)]
34pub enum JsonPathSegment {
35 /// An object key after JSON escape decoding.
36 Key(
37 /// The decoded key text, without its surrounding JSON string syntax.
38 String,
39 ),
40 /// An array element index.
41 Index(
42 /// The zero-based position of the element within its containing array.
43 usize,
44 ),
45}