Struct JsonDecodeError

Source

pub struct JsonDecodeError<R = JsonResource, Q = usize>where
    Q: Copy + Debug,
{ /* private fields */ }

Expand description

Failure produced by either strict or normalizing JSON decoding.

Internal variants are private so callers branch through stable semantic accessors rather than depending on scanner, normalizer, or Serde details.

§Type Parameters

R - Resource identity attached to budget failures.
Q - Quantity representation attached to budget failures.

§Examples

use qubit_json::decode::{JsonDecodeError, JsonDecodeErrorKind, JsonDecoder};
use serde_json::Value;

let mut decoder = JsonDecoder::unlimited();
let error: JsonDecodeError = decoder
    .decode_str::<Value>("")
    .expect_err("empty input must be rejected");
assert_eq!(error.kind(), JsonDecodeErrorKind::InvalidJson);

Implementations§

Source §

impl<R, Q> JsonDecodeError<R, Q>
where Q: Copy + Debug,

Source

pub const fn kind(&self) -> JsonDecodeErrorKind

Returns the stable failure category.

§Returns

The category describing which kind of decode operation failed.

Source

pub const fn materialization_error_reason( &self, ) -> Option<JsonMaterializationErrorReason>

Returns the safe reason for a unique-key intermediate-tree failure.

Returns Some(reason) when unique-key tree construction failed because of a duplicate key or a defensive unrepresentable admitted number. The legacy depth-limit reason remains for source compatibility, but the shared builder has no fixed container cap and configured depth failures are reported as budget errors. Returns None for lexical, input, budget, and target-deserialization failures. The reason remains available under redacted diagnostics and contains no input-derived text. Read it before consuming the error with Self::into_source.

§Examples

use qubit_json::decode::{JsonDecoder, JsonMaterializationErrorReason};
use serde_json::Value;

let mut decoder = JsonDecoder::unlimited();
let error = decoder
    .decode_unique_str::<Value>(r#"{"id":1,"id":2}"#)
    .expect_err("duplicate keys must be rejected");
assert_eq!(
    error.materialization_error_reason(),
    Some(JsonMaterializationErrorReason::DuplicateKey),
);

Source

pub const fn stage(&self) -> JsonDecodeStage

Returns the semantic stage that produced the failure.

§Returns

The pipeline stage at which the failure was recorded.

Source

pub const fn diagnostic_policy(&self) -> DiagnosticPolicy

Returns the diagnostic policy applied while constructing this error.

§Returns

The policy that determines whether input-derived details are retained.

Source

pub const fn raw_input_bytes(&self) -> usize

Returns the raw input length observed at the decoding boundary.

For slice-based entry points, this is the complete input slice length, including when input admission rejects the slice before processing it. For decode_input, this is the length of the prefix read and retained before the error; a byte consumed only to probe past the input budget is excluded. The value therefore does not universally represent bytes charged to the budget or the session’s cumulative input usage.

§Returns

The raw input length observed for the input that caused this error.

Source

pub const fn normalized_input_bytes(&self) -> Option<usize>

Returns the predicted normalized text length when it is available.

A value may be present even when a budget rejected the input before normalized text was allocated or rewritten. This reports a target length, not proof that a normalized document was produced or charged.

§Returns

Some(length) when normalization determined a target length, or None when the failure occurred before that length was available.

Source

pub const fn read_error_kind(&self) -> Option<ErrorKind>

Returns the standard I/O error category for a read failure.

§Returns

Some(kind) for a read failure, or None for other failure kinds.

Source

pub fn read_error(&self) -> Option<&Error>

Returns the retained original I/O error for detailed read diagnostics.

§Returns

The original read error when detailed diagnostics retained it, or None when the error is not a read failure or its source was not retained.

Source

pub const fn line(&self) -> Option<usize>

Returns the one-based error line when available.

Invalid-JSON coordinates come from the lexical scanner. Deserialize coordinates preserve serde_json’s one-based line values, including unique-key materialization errors. For a deserialize error, a backend line of zero is reported as None.

§Returns

Some(line) for failures with source coordinates, otherwise None.

Source

pub const fn column(&self) -> Option<usize>

Returns the one-based error column when available.

Invalid-JSON columns count UTF-8 characters, while deserialize columns preserve serde_json’s byte-based column. Unique-key materialization columns count bytes before the offending token, with only LF starting a new line. For a deserialize error, a backend column of zero is reported as None.

§Returns

Some(column) for failures with source coordinates, otherwise None.

Source

pub const fn syntax_error(&self) -> Option<&JsonSyntaxError>

Returns the structured syntax failure for invalid JSON.

§Returns

A borrowed syntax error when parsing failed, otherwise None.

Source

pub const fn budget_error(&self) -> Option<&MeasuredBudgetError<R, Q>>

Returns the complete measured-budget failure when present.

§Returns

A borrowed budget error when resource accounting rejected the input, otherwise None.

Source

pub const fn utf8_valid_up_to(&self) -> Option<usize>

Returns the valid UTF-8 prefix length for invalid byte input.

§Returns

Some(bytes) for an invalid UTF-8 failure, or None for other failure kinds.

Source

pub const fn utf8_error_len(&self) -> Option<usize>

Returns the invalid UTF-8 sequence length when known.

§Returns

The length of the invalid sequence when the decoder can determine it, otherwise None.

Source

pub const fn expected_top_level(&self) -> Option<JsonRootKind>

Returns the expected top-level kind for a constrained decode failure.

§Returns

The required root kind when a constrained operation failed, otherwise None.

Source

pub const fn actual_top_level(&self) -> Option<JsonRootKind>

Returns the observed top-level kind for a constrained decode failure.

§Returns

The root kind observed in the valid document, otherwise None.

Source

pub fn into_source(self) -> JsonDecodeErrorSource<R, Q>

Consumes this error and returns its owned operation-level source.

The materialization reason returned by Self::materialization_error_reason is stored separately and is not included in the returned source. Read it before consuming this error. Input-derived third-party sources remain present only when the decoder used DiagnosticPolicy::Detailed.

§Returns

The owned budget, input, syntax, top-level, or deserialization source retained by this error. Any materialization reason is not returned.

§Examples

use qubit_json::decode::{
    JsonDecodeErrorSource, JsonDecoder, JsonMaterializationErrorReason,
};

let error = JsonDecoder::unlimited()
    .decode_value_str(r#"{"id":1,"id":2}"#)
    .expect_err("duplicate keys must be rejected");
let reason = error.materialization_error_reason();
let source = error.into_source();

assert_eq!(reason, Some(JsonMaterializationErrorReason::DuplicateKey));
assert!(matches!(source, JsonDecodeErrorSource::Deserialize { .. }));