qubit_json/format/
json_pretty_error_kind.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//! Categories of JSON token formatting failures.
9
10use std::fmt;
11
12/// Stable category for a token formatting failure.
13///
14/// The category distinguishes invalid input, output limits, capacity failures,
15/// and write failures without exposing implementation-specific details.
16///
17/// # Examples
18///
19/// ```
20/// use qubit_json::format::JsonPrettyErrorKind;
21///
22/// let kind = JsonPrettyErrorKind::Syntax;
23/// assert_eq!(kind.to_string(), "invalid JSON syntax");
24/// ```
25#[non_exhaustive]
26#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
27pub enum JsonPrettyErrorKind {
28    /// The input is not one complete syntactically valid JSON value.
29    Syntax,
30    /// The formatted bytes exceed the caller-provided maximum.
31    OutputLimit,
32    /// Checked length arithmetic or allocation could not be completed.
33    Capacity,
34    /// The output rejected a write; an accepted prefix may remain.
35    Io,
36}
37
38impl fmt::Display for JsonPrettyErrorKind {
39    /// Writes the stable human-readable description of this failure category.
40    ///
41    /// # Parameters
42    ///
43    /// * `formatter` — the output formatter receiving the description.
44    ///   Formatting stops if it reports a write error.
45    ///
46    /// # Returns
47    ///
48    /// Returns `Ok(())` after writing the description, or the formatter's
49    /// error if the output sink rejects the write.
50    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
51        formatter.write_str(match self {
52            Self::Syntax => "invalid JSON syntax",
53            Self::OutputLimit => "formatted output limit exceeded",
54            Self::Capacity => "formatting capacity exceeded",
55            Self::Io => "formatted output write failed",
56        })
57    }
58}
qubit_json/format/json_pretty_error_kind.rs

qubit_json/format/
json_pretty_error_kind.rs
