Skip to main content

JsonDecoder

qubit_json::decode

Struct JsonDecoder 

Source 
pub struct JsonDecoder<'budget, R = JsonResource, Q = usize>
where
    Q: ResourceQuantity,
{ /* private fields */ }
Expand description

Strictly decodes complete JSON documents while retaining cumulative usage.

This facade performs no normalization. It accepts integers from i64::MIN through u64::MAX, requires finite floating-point values, supports values borrowing from its input, and exposes caller-provided Serde seeds.

§Type Parameters

  • 'budget - Lifetime of the resource budget borrowed by the decoder’s cumulative session.
  • R - Resource identity type tracked by the session.
  • Q - Quantity type used for resource limits and accounting.

§Examples

use qubit_json::decode::JsonDecoder;
use serde_json::Value;

let mut decoder = JsonDecoder::unlimited();
let value = decoder.decode_str::<Value>(r#"{"ok":true}"#)?;
assert_eq!(value["ok"], true);

Implementations§

Source§

impl<R, Q> JsonDecoder<'static, R, Q>
where R: Clone, Q: ResourceQuantity,

Source

pub fn with_limits(limits: JsonDecodeLimits<R, Q>) -> Self

Creates a decoder with a cumulative session built from explicit limits.

§Parameters
  • limits - Input and decoded-value limits used by the cumulative session.
§Returns

A decoder whose accounting starts empty and is constrained by limits.

Source§

impl JsonDecoder<'static, JsonResource, usize>

Source

pub fn unlimited() -> Self

Creates a decoder with no configured input or value limits.

§Returns

A decoder using the standard resource identities with all limits disabled.

Source§

impl<'budget, R, Q> JsonDecoder<'budget, R, Q>
where R: Clone, Q: ResourceQuantity,

Source

pub fn decode_value_utf8( &mut self, input: &[u8], ) -> Result<SafeJsonValue, JsonDecodeError<R, Q>>

Decodes one complete document into a guarded value and rejects duplicate keys.

§Parameters
  • input - Complete UTF-8 JSON document.
§Returns

The protected owned value after input and value accounting succeed.

§Errors

Returns a structured error for invalid UTF-8, syntax, numeric range, duplicate keys, or configured resource limits.

Source

pub fn decode_value_str( &mut self, input: &str, ) -> Result<SafeJsonValue, JsonDecodeError<R, Q>>

UTF-8 string form of Self::decode_value_utf8.

§Parameters
  • input - Complete JSON document text.
§Returns

The protected owned value.

§Errors

Returns a structured error for syntax, numeric range, duplicate keys, or configured resource limits.

Source

pub fn decode_value_input<I: ByteInput + ?Sized>( &mut self, input: &mut I, ) -> Result<SafeJsonValue, JsonDecodeError<R, Q>>

Reads one unique-key document through EOF and decodes it into a guarded value.

Reads in bounded chunks, with at most one probe byte beyond an active input limit. Accepted bytes remain charged when later validation fails.

§Parameters
  • input - Byte input read through EOF.
§Returns

The protected owned value.

§Errors

Returns read, input-budget, UTF-8, syntax, numeric-range, duplicate-key, or value-budget failures.

Source

pub fn decode_unique_validated_utf8<E, F>( &mut self, input: &[u8], options: &JsonValidatedDecodeOptions, number_policy: F, ) -> Result<SafeJsonValue, JsonValidatedDecodeError<E, R, Q>>
where F: for<'call> FnMut(&'call [JsonPathSegment], JsonNumberToken<'call>) -> Result<JsonNumberPolicy, E>,

Decodes one document while applying a caller policy to each source number.

The callback runs in source order after a number token is syntactically complete and before its configured representation range is checked. It receives the typed path and borrowed source spelling; its first error stops scanning immediately. Object keys must be unique after decoding. Side effects performed by the callback are not rolled back if later syntax, delimiter, or budget validation fails. The string and input forms of this method have the same callback contract.

use std::cell::Cell;
use std::convert::Infallible;
use qubit_json::decode::JsonDecoder;
use qubit_json::decode::JsonNumberPolicy;
use qubit_json::decode::JsonValidatedDecodeOptions;

let calls = Cell::new(0);
let result = JsonDecoder::unlimited().decode_unique_validated_str(
    "[1,]",
    &JsonValidatedDecodeOptions::builder().build(),
    |_, _| {
        calls.set(calls.get() + 1);
        Ok::<_, Infallible>(JsonNumberPolicy::Preserve)
    },
);
assert!(result.is_err());
assert_eq!(calls.get(), 1);
§Parameters
  • input - Complete UTF-8 JSON document.
  • options - Root, number model, and per-document source-token limits.
  • number_policy - Synchronous policy called for each complete number.
§Returns

The protected owned value after complete scanning and accounting.

§Errors

Returns structured decode errors, callback errors with source offsets, exact-safe-integer errors, or validated-limit failures.

Source

pub fn decode_unique_validated_str<E, F>( &mut self, input: &str, options: &JsonValidatedDecodeOptions, number_policy: F, ) -> Result<SafeJsonValue, JsonValidatedDecodeError<E, R, Q>>
where F: for<'call> FnMut(&'call [JsonPathSegment], JsonNumberToken<'call>) -> Result<JsonNumberPolicy, E>,

UTF-8 string form of Self::decode_unique_validated_utf8, with the same callback side-effect contract documented there.

§Parameters
  • input - Complete JSON document text.
  • options - Root, number model, and per-document source-token limits.
  • number_policy - Synchronous number policy callback.
§Returns

The protected owned value.

§Errors

Returns decode, callback, exact-safe-integer, or validated-limit errors.

Source

pub fn decode_unique_validated_input<E, F, I>( &mut self, input: &mut I, options: &JsonValidatedDecodeOptions, number_policy: F, ) -> Result<SafeJsonValue, JsonValidatedDecodeError<E, R, Q>>
where I: ByteInput + ?Sized, F: for<'call> FnMut(&'call [JsonPathSegment], JsonNumberToken<'call>) -> Result<JsonNumberPolicy, E>,

Reads a byte input through EOF and applies a source-number policy during decoding.

Accepted input bytes remain charged if the callback or later validation fails; value charges commit only after the complete document succeeds. Callback side effects are not rolled back on failure, as documented for Self::decode_unique_validated_utf8.

§Parameters
  • input - Byte input read through EOF.
  • options - Root, number model, and per-document token limits.
  • number_policy - Synchronous callback for each source number.
§Returns

The protected owned value.

§Errors

Returns structured decode, read, callback, exact-integer, or limit errors.

Source

pub fn decode_input_with_number_model<T, I>( &mut self, input: &mut I, model: JsonDecodeNumberModel, ) -> Result<T, JsonDecodeError<R, Q>>
where T: DeserializeOwned, I: ByteInput + ?Sized,

Decodes one byte input using an explicit integer/fallback number model.

The number model controls whether an integer token outside i64/u64 is admitted. With the fallback model, that token is admitted only when it converts to finite f64. Decimal and exponent forms use the finite-float rule in both models.

The resulting representation is produced by Serde for T and can depend on the active serde_json features. For deterministic numeric projection, use validated decoding with JsonNumberPolicy::Preserve; it materializes fallback integers as finite f64 values.

§Parameters
  • input - Byte input read through EOF.
  • model - Integer representation model for admitted source numbers.
§Returns

The owned value produced by Serde. Its numeric representation follows T and the active Serde implementation and features.

§Errors

Returns read, UTF-8, syntax, numeric-range, budget, or Serde errors.

Source

pub const fn new(session: JsonDecodeSession<'budget, R, Q>) -> Self

Creates a strict decoder around a reusable cumulative session.

§Parameters
  • session - Cumulative session that receives input and decoded-value charges.
§Returns

A decoder that owns session until it is consumed by Self::into_session.

Source

pub const fn diagnostic_policy(&self) -> DiagnosticPolicy

Returns the configured diagnostic policy without changing the decoder.

§Returns

The policy used when constructing input-derived decode errors.

Source

pub const fn session(&self) -> &JsonDecodeSession<'budget, R, Q>

Returns the cumulative session for read-only inspection.

The returned reference is borrowed from the decoder and exposes the charges accumulated by completed operations.

§Returns

A shared reference to the decoder’s cumulative session.

Source

pub const fn session_mut(&mut self) -> &mut JsonDecodeSession<'budget, R, Q>

Returns mutable access to the cumulative session.

Mutating the session changes the limits and accounting state used by subsequent operations.

§Returns

A mutable reference tied to the decoder’s lifetime.

Source

pub const fn with_diagnostic_policy(self, policy: DiagnosticPolicy) -> Self

Configures whether input-derived error sources are retained.

The default is DiagnosticPolicy::Redacted. Selecting DiagnosticPolicy::Detailed may retain source errors containing fragments or structural details derived from the input.

§Parameters
  • policy - Diagnostic retention policy for failures produced by this decoder.
§Returns

The decoder with the requested policy; its existing session is retained.

Source

pub fn into_session(self) -> JsonDecodeSession<'budget, R, Q>

Consumes the decoder and returns its cumulative session.

This transfers ownership of all accumulated accounting state without performing another decode or resetting the session.

§Returns

The session previously owned by this decoder.

Source

pub fn decode_str<'de, T>( &mut self, input: &'de str, ) -> Result<T, JsonDecodeError<R, Q>>
where T: Deserialize<'de>,

Decodes one complete JSON string and permits results borrowing input.

§Type Parameters
  • T - Target type deserialized from the complete document.
§Parameters
  • input - UTF-8 JSON text. The returned value may borrow from it.
§Returns

The deserialized value on success.

§Errors

Returns a structured error when input accounting, UTF-8 validation, JSON parsing, or Serde deserialization fails.

Source

pub fn decode_utf8<'de, T>( &mut self, input: &'de [u8], ) -> Result<T, JsonDecodeError<R, Q>>
where T: Deserialize<'de>,

Decodes one complete UTF-8 JSON byte slice and permits borrowed results.

§Type Parameters
  • T - Target type deserialized from the complete document.
§Parameters
  • input - Complete UTF-8 JSON bytes. The returned value may borrow from this slice.
§Returns

The deserialized value on success.

§Errors

Returns a structured error when accounting, UTF-8 validation, JSON parsing, or Serde deserialization fails.

Source

pub fn decode_input<T, I>( &mut self, input: &mut I, ) -> Result<T, JsonDecodeError<R, Q>>
where T: DeserializeOwned, I: Input<Item = u8> + ?Sized,

Decodes a complete document from an item-oriented byte input through EOF.

Without an input-byte limit, the input is read in fixed-size chunks. With a limit, each read is bounded by the remaining allowance plus at most one probe byte. The probe distinguishes an input ending exactly at the limit from an oversized input; it is neither charged nor buffered, and cannot be returned to the input source. The complete admitted document is buffered in memory because the returned value must not borrow from the temporary buffer. Without an input-byte limit, this buffering has no implicit size cap.

§Parameters
  • input - Mutable byte input read through EOF.
§Errors

Returns a structured error for read failures, input-budget rejection, invalid UTF-8, invalid JSON, or target deserialization failures.

Source

pub fn decode_seed_str<'de, S>( &mut self, seed: S, input: &'de str, ) -> Result<S::Value, JsonDecodeError<R, Q>>
where S: DeserializeSeed<'de>,

Decodes a JSON string through a caller-provided Serde seed.

§Type Parameters
  • S - Seed controlling construction of the decoded value.
§Parameters
  • seed - Serde seed used to deserialize the document.
  • input - Complete JSON text, which the seed may borrow from.
§Returns

The value produced by seed.

§Errors

Returns a structured error when accounting, parsing, or seeded deserialization fails.

Source

pub fn decode_seed_utf8<'de, S>( &mut self, seed: S, input: &'de [u8], ) -> Result<S::Value, JsonDecodeError<R, Q>>
where S: DeserializeSeed<'de>,

Decodes a UTF-8 byte slice through a caller-provided Serde seed.

§Type Parameters
  • S - Seed controlling construction of the decoded value.
§Parameters
  • seed - Serde seed used to deserialize the document.
  • input - Complete UTF-8 JSON bytes, which the seed may borrow from.
§Returns

The value produced by seed.

§Errors

Returns a structured error when accounting, UTF-8 validation, parsing, or seeded deserialization fails.

Source

pub fn decode_unique_str<T>( &mut self, input: &str, ) -> Result<T, JsonDecodeError<R, Q>>
where T: DeserializeOwned,

Decodes a unique-key JSON document into an owned target.

The document is first materialized under the strict number contract, then exposed as native Serde events even with arbitrary_precision. Source construction uses the configured value depth budget and has no separate fixed container limit. Targets cannot borrow the input, and RawValue targets receive reconstructed JSON.

§Errors

Returns an input, syntax, budget, duplicate-key, construction-depth, or target-deserialization error. Value usage commits only on success.

Source

pub fn decode_unique_utf8<T>( &mut self, input: &[u8], ) -> Result<T, JsonDecodeError<R, Q>>
where T: DeserializeOwned,

Decodes a unique-key UTF-8 JSON document into an owned target.

See Self::decode_unique_str for numeric and materialization rules.

§Errors

Returns an input, UTF-8, syntax, budget, materialization, or target error.

Source

pub fn decode_unique_seed_utf8<S, T>( &mut self, seed: S, input: &[u8], ) -> Result<T, JsonDecodeError<R, Q>>
where S: for<'de> DeserializeSeed<'de, Value = T>,

Decodes unique-key JSON through a seed producing an owned result.

The seed receives native scalar, sequence, and map events from an intermediate strict JSON tree. Input and value budgets cover the source document. The temporary tree and target can coexist during decoding; these lexical budgets are not a precise heap-memory bound. Object iteration follows serde_json::Map ordering. The target’s own Serde semantics still apply: use DuplicateKeyRejectingJsonValue instead of a bare serde_json::Value to preserve literal private keys.

§Errors

Returns a structured decode error for input admission, invalid syntax, duplicate keys, configured value-depth failure, or seed failure. Materialization errors retain source coordinates; target errors have no original source position and are redacted by default.

Source

pub fn decode_object_str<'de, T>( &mut self, input: &'de str, ) -> Result<T, JsonDecodeError<R, Q>>
where T: Deserialize<'de>,

Decodes a complete JSON string while requiring a top-level object.

The top-level check is performed before the decoded value is committed, so an array, scalar, or otherwise valid non-object document is rejected.

§Type Parameters
  • T - Target type deserialized from the object document.
§Parameters
  • input - Complete JSON text, which the returned value may borrow.
§Returns

The deserialized object value on success.

§Errors

Returns a structured error for accounting, parsing, top-level-kind, or deserialization failures.

Source

pub fn decode_object_utf8<'de, T>( &mut self, input: &'de [u8], ) -> Result<T, JsonDecodeError<R, Q>>
where T: Deserialize<'de>,

Decodes a complete UTF-8 byte slice while requiring a top-level object.

A syntactically valid array or scalar is rejected by the top-level constraint before the decoded value is committed.

§Type Parameters
  • T - Target type deserialized from the object document.
§Parameters
  • input - Complete UTF-8 JSON bytes, which the returned value may borrow.
§Returns

The deserialized object value on success.

§Errors

Returns a structured error for accounting, UTF-8 validation, parsing, top-level-kind, or deserialization failures.

Source

pub fn decode_array_str<'de, T>( &mut self, input: &'de str, ) -> Result<Vec<T>, JsonDecodeError<R, Q>>
where T: Deserialize<'de>,

Decodes a complete JSON string while requiring a top-level array.

§Type Parameters
  • T - Element type deserialized from the array.
§Parameters
  • input - Complete JSON text, which the returned elements may borrow.
§Returns

The decoded array elements on success.

§Errors

Returns a structured error for accounting, parsing, top-level-kind, or deserialization failures.

Source

pub fn decode_array_utf8<'de, T>( &mut self, input: &'de [u8], ) -> Result<Vec<T>, JsonDecodeError<R, Q>>
where T: Deserialize<'de>,

Decodes a complete UTF-8 byte slice while requiring a top-level array.

§Type Parameters
  • T - Element type deserialized from the array.
§Parameters
  • input - Complete UTF-8 JSON bytes, which the returned elements may borrow.
§Returns

The decoded array elements on success.

§Errors

Returns a structured error for accounting, UTF-8 validation, parsing, top-level-kind, or deserialization failures.

Source

pub fn validate_str(&mut self, input: &str) -> Result<(), JsonDecodeError<R, Q>>

Validates and accounts for one complete JSON string without materializing a target value.

§Parameters
  • input - Complete JSON text to validate and account for.
§Returns

Ok(()) after the complete document is valid and accounted for.

§Errors

Returns a structured error when accounting or JSON parsing fails. No target value is allocated; str input is already valid UTF-8.

Source

pub fn validate_utf8( &mut self, input: &[u8], ) -> Result<(), JsonDecodeError<R, Q>>

Validates and accounts for one complete UTF-8 JSON byte slice without materializing a target value.

§Parameters
  • input - Complete UTF-8 JSON bytes to validate and account for.
§Returns

Ok(()) after the complete document is valid and accounted for.

§Errors

Returns a structured error when accounting, UTF-8 validation, or JSON parsing fails. No target value is allocated.

Trait Implementations§

Source§

impl<'budget, R: Debug, Q> Debug for JsonDecoder<'budget, R, Q>
where Q: ResourceQuantity + Debug,

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'budget, R = JsonResource, Q = usize> !UnwindSafe for JsonDecoder<'budget, R, Q>

§

impl<'budget, R, Q> Freeze for JsonDecoder<'budget, R, Q>
where JsonDecodeEngine<'budget, R, Q>: Freeze,

§

impl<'budget, R, Q> RefUnwindSafe for JsonDecoder<'budget, R, Q>
where JsonDecodeEngine<'budget, R, Q>: RefUnwindSafe,

§

impl<'budget, R, Q> Send for JsonDecoder<'budget, R, Q>
where JsonDecodeEngine<'budget, R, Q>: Send,

§

impl<'budget, R, Q> Sync for JsonDecoder<'budget, R, Q>
where JsonDecodeEngine<'budget, R, Q>: Sync,

§

impl<'budget, R, Q> Unpin for JsonDecoder<'budget, R, Q>
where JsonDecodeEngine<'budget, R, Q>: Unpin,

§

impl<'budget, R, Q> UnsafeUnpin for JsonDecoder<'budget, R, Q>
where JsonDecodeEngine<'budget, R, Q>: UnsafeUnpin,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.