1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
// =============================================================================
// Copyright (c) 2026 Haixing Hu.
//
// SPDX-License-Identifier: Apache-2.0
//
// Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Defines stable categories for JSON decoding failures.
use std::fmt;
use std::str::FromStr;
/// Represents the coarse category of a JSON decoding failure.
///
/// This exhaustive enum is the stable branching contract shared by strict and
/// normalizing decoders.
///
/// # Examples
///
/// ```
/// use qubit_json::decode::JsonDecodeErrorKind;
///
/// let kind = "invalid_json".parse::<JsonDecodeErrorKind>()?;
/// assert_eq!(kind, JsonDecodeErrorKind::InvalidJson);
/// # Ok::<(), &'static str>(())
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum JsonDecodeErrorKind {
/// Reading bytes from the input failed.
Read,
/// A configured resource budget rejected a measurement.
Budget,
/// Normalization produced no JSON document from the supplied input.
EmptyInput,
/// Raw byte input was not valid UTF-8.
InvalidUtf8,
/// Input was not one valid JSON document under the numeric contract.
InvalidJson,
/// A valid document had an unexpected top-level kind.
UnexpectedTopLevel,
/// A valid admitted document could not deserialize into the target type.
Deserialize,
}
impl fmt::Display for JsonDecodeErrorKind {
/// Writes the stable snake-case category name.
///
/// # Parameters
///
/// * `formatter` - Destination for the category name.
///
/// # Returns
///
/// `Ok(())` when the category name is written successfully.
///
/// # Errors
///
/// Returns the formatter's error if the destination rejects the write.
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::Read => "read",
Self::Budget => "budget",
Self::EmptyInput => "empty_input",
Self::InvalidUtf8 => "invalid_utf8",
Self::InvalidJson => "invalid_json",
Self::UnexpectedTopLevel => "unexpected_top_level",
Self::Deserialize => "deserialize",
})
}
}
impl FromStr for JsonDecodeErrorKind {
/// Uses a static message to report unsupported category names.
type Err = &'static str;
/// Parses a stable category name without ASCII case sensitivity.
///
/// # Parameters
///
/// * `value` - Category name to parse.
///
/// # Returns
///
/// The matching JSON decoding error category.
///
/// # Errors
///
/// Returns `"unknown JsonDecodeErrorKind"` when `value` does not match a
/// supported category name.
fn from_str(value: &str) -> Result<Self, Self::Err> {
if value.eq_ignore_ascii_case("read") {
Ok(Self::Read)
} else if value.eq_ignore_ascii_case("budget") {
Ok(Self::Budget)
} else if value.eq_ignore_ascii_case("empty_input") {
Ok(Self::EmptyInput)
} else if value.eq_ignore_ascii_case("invalid_utf8") {
Ok(Self::InvalidUtf8)
} else if value.eq_ignore_ascii_case("invalid_json") {
Ok(Self::InvalidJson)
} else if value.eq_ignore_ascii_case("unexpected_top_level") {
Ok(Self::UnexpectedTopLevel)
} else if value.eq_ignore_ascii_case("deserialize") {
Ok(Self::Deserialize)
} else {
Err("unknown JsonDecodeErrorKind")
}
}
}