qubit_json/decode/json_materialization_error_reason.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//! Structured reasons for failures while materializing unique-key JSON.
9
10/// Describes why an admitted unique-key document could not be materialized.
11///
12/// The reason is available independently of diagnostic source retention and
13/// never contains input-derived text.
14///
15/// # Examples
16///
17/// ```
18/// use qubit_json::decode::JsonMaterializationErrorReason;
19///
20/// let reason = JsonMaterializationErrorReason::DuplicateKey;
21/// assert_eq!(reason, JsonMaterializationErrorReason::DuplicateKey);
22/// ```
23#[non_exhaustive]
24#[must_use]
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
26pub enum JsonMaterializationErrorReason {
27 /// A decoded object key appeared more than once.
28 DuplicateKey,
29 /// Historical compatibility reason; the shared builder no longer produces
30 /// it.
31 DepthLimit {
32 /// Maximum number of nested containers accepted during construction.
33 limit: usize,
34 },
35 /// An admitted number could not be represented by the intermediate tree.
36 InvalidNumber,
37}