qubit_json/format/
json_pretty_error.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//! Errors returned by JSON token formatting.
9
10use std::error::Error;
11use std::fmt;
12
13use super::JsonPrettyErrorKind;
14
15/// Error from validating, planning, or writing formatted JSON tokens.
16///
17/// Syntax errors can carry a byte offset into the input, while output limits,
18/// capacity failures, and I/O errors do not. A source error is available only
19/// when the failure has an underlying cause.
20///
21/// ```
22/// use std::error::Error;
23///
24/// use qubit_json::format::JsonPrettyErrorKind;
25/// use qubit_json::format::JsonPrettyOptions;
26/// use qubit_json::format::format_json_tokens;
27///
28/// let options = JsonPrettyOptions::builder().build()?;
29/// let syntax = format_json_tokens(b"{}x", &options, None).expect_err("trailing data is invalid");
30/// assert_eq!(syntax.kind(), JsonPrettyErrorKind::Syntax);
31/// assert_eq!(syntax.offset(), Some(2));
32/// assert!(syntax.source().is_some());
33///
34/// let limit = format_json_tokens(b"0", &options, Some(0)).expect_err("zero output allowance");
35/// assert_eq!(limit.kind(), JsonPrettyErrorKind::OutputLimit);
36/// assert_eq!(limit.offset(), None);
37/// # Ok::<(), Box<dyn std::error::Error>>(())
38/// ```
39pub struct JsonPrettyError {
40    /// Stable category used to distinguish formatting failure classes.
41    kind: JsonPrettyErrorKind,
42    /// Available zero-based byte position in the source input, when applicable.
43    offset: Option<usize>,
44    /// Optional underlying cause, exposed separately through [`Error::source`].
45    source: Option<Box<dyn Error + Send + Sync>>,
46}
47
48impl JsonPrettyError {
49    /// Creates an error with its category, optional source position, and cause.
50    ///
51    /// `offset` is a zero-based byte coordinate in the input, not a character
52    /// index. `source` may be absent, including for errors whose category is
53    /// [`JsonPrettyErrorKind::Syntax`].
54    ///
55    /// # Parameters
56    ///
57    /// * `kind` — stable category of the formatting failure.
58    /// * `offset` — source input byte coordinate when one is available.
59    /// * `source` — optional underlying error providing additional cause
60    ///   context.
61    pub(super) fn new(
62        kind: JsonPrettyErrorKind,
63        offset: Option<usize>,
64        source: Option<Box<dyn Error + Send + Sync>>,
65    ) -> Self {
66        Self { kind, offset, source }
67    }
68
69    /// Returns the stable error category.
70    pub fn kind(&self) -> JsonPrettyErrorKind {
71        self.kind
72    }
73
74    /// Returns an available zero-based byte coordinate in the source input.
75    ///
76    /// `None` means the error is not associated with a source position; it does
77    /// not mean byte zero. Not every syntax error is guaranteed to have an
78    /// offset.
79    ///
80    /// # Returns
81    ///
82    /// The source input byte offset, or `None` when no coordinate is available.
83    pub fn offset(&self) -> Option<usize> {
84        self.offset
85    }
86}
87
88impl fmt::Debug for JsonPrettyError {
89    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
90        formatter
91            .debug_struct("JsonPrettyError")
92            .field("kind", &self.kind)
93            .field("offset", &self.offset)
94            .finish()
95    }
96}
97
98impl fmt::Display for JsonPrettyError {
99    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
100        match self.offset {
101            Some(offset) => write!(formatter, "{} at byte offset {offset}", self.kind),
102            None => fmt::Display::fmt(&self.kind, formatter),
103        }
104    }
105}
106
107impl Error for JsonPrettyError {
108    /// Returns the optional underlying parsing, allocation, or I/O cause.
109    ///
110    /// Formatting and debug output do not include this cause automatically.
111    fn source(&self) -> Option<&(dyn Error + 'static)> {
112        self.source.as_deref().map(|error| error as _)
113    }
114}
qubit_json/format/json_pretty_error.rs

qubit_json/format/
json_pretty_error.rs
