qubit-json 0.12.2

Resource-aware infrastructure for lenient and strict JSON processing
Documentation 
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
110
111
112
113
114
115
116
117
118
119
120
121

// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Validated JSON decode configuration.

use super::JsonDecodeNumberModel;
use super::JsonRootKind;
use super::JsonValidatedAdmissionPolicy;
use super::JsonValidatedDecodeOptionsBuilder;

/// Generic structural and source-token limits for validated decoding.
///
/// By default, no additional limits are imposed and the number model is
/// `Integer64`. A limit set to `Some(0)` is a real zero-item/zero-byte limit;
/// `None` means that the corresponding additional limit is disabled. Value
/// nodes and object-key nodes both count toward the node limit. String limits
/// count the source spelling inside each token, excluding quotes and
/// including escape bytes such as the six bytes in `\u0061`.
///
/// # Examples
///
/// ```
/// use qubit_json::decode::{JsonDecoder, JsonNumberPolicy, JsonValidatedDecodeOptions};
///
/// let options = JsonValidatedDecodeOptions::builder()
///     .max_value_and_key_nodes(3)
///     .max_encoded_string_bytes(8)
///     .build();
/// let value = JsonDecoder::unlimited().decode_unique_validated_str(
///     r#"{"id":42}"#,
///     &options,
///     |_path, _token| Ok::<_, std::convert::Infallible>(JsonNumberPolicy::ExactSafeInteger),
/// )?;
/// assert_eq!(value.as_value()["id"].as_i64(), Some(42));
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JsonValidatedDecodeOptions {
    /// Required root kind, when the caller configured one.
    pub(super) root_kind: Option<JsonRootKind>,
    /// Token admission order for validated decoding.
    pub(super) admission_policy: JsonValidatedAdmissionPolicy,
    /// Representation model used for numbers selected for preservation.
    pub(super) number_model: JsonDecodeNumberModel,
    /// Optional combined count for value nodes and object-key nodes.
    pub(super) max_value_and_key_nodes: Option<usize>,
    /// Optional maximum source bytes inside each string token.
    pub(super) max_encoded_string_bytes: Option<usize>,
}

impl JsonValidatedDecodeOptions {
    /// Creates a builder with no extra limits and the `Integer64` model.
    ///
    /// # Returns
    ///
    /// A builder whose optional root kind and additional limits are unset.
    #[inline]
    pub fn builder() -> JsonValidatedDecodeOptionsBuilder {
        JsonValidatedDecodeOptionsBuilder::default()
    }

    /// Returns the optional required root kind. `None` accepts any root kind.
    ///
    /// # Returns
    ///
    /// The required root kind, or `None` when no root-kind restriction applies.
    #[inline]
    pub const fn root_kind(&self) -> Option<JsonRootKind> {
        self.root_kind
    }

    /// Returns the token admission order used by validated decoding.
    ///
    /// # Returns
    ///
    /// The configured policy. The default is
    /// [`JsonValidatedAdmissionPolicy::Immediate`].
    #[must_use]
    #[inline]
    pub const fn admission_policy(&self) -> JsonValidatedAdmissionPolicy {
        self.admission_policy
    }

    /// Returns the selected number model.
    ///
    /// # Returns
    ///
    /// The number representation model used for preserved numbers.
    #[must_use]
    #[inline]
    pub const fn number_model(&self) -> JsonDecodeNumberModel {
        self.number_model
    }

    /// Returns the optional per-document value-and-key node limit. `None`
    /// disables this additional limit; `Some(0)` permits no nodes.
    ///
    /// # Returns
    ///
    /// The configured combined node limit, or `None` when it is disabled.
    #[inline]
    pub const fn max_value_and_key_nodes(&self) -> Option<usize> {
        self.max_value_and_key_nodes
    }

    /// Returns the optional per-token source-string byte limit. It excludes
    /// the quotes and includes escape spelling bytes. `None` disables this
    /// additional limit; `Some(0)` permits only empty string token contents.
    ///
    /// # Returns
    ///
    /// The configured per-token source-byte limit, or `None` when disabled.
    #[inline]
    pub const fn max_encoded_string_bytes(&self) -> Option<usize> {
        self.max_encoded_string_bytes
    }
}