Struct GenericDocument

pub struct GenericDocument<'a, Backing> { /* private fields */ }

A parsed JSON payload.

This type is a read-only view into the JSON payload.

This structure is faster to parse than Value, but it is more work to interact with because the entire payload is stored in a single list internally.

The list of Nodes is sequentially ordered by the order in which they appear in the document. This means that the first Node tells us what the root type of the document is.

The nodes Node::Null, Node::Boolean, Node::String, and Node::Number all directly represent a Value with the same name.

Node::Object contains a length field, which lets us know how many key-value pairs will appear after the object’s node. Object keys are guaranteed to be Node::Strings, but object values can be any Node variant. This means care must be taken to handle nested structures.

Node::Array also contains a length field, which lets us know how many values follow the array’s node. Because array values can be any type, care must be taken to handle nested structures correctly.

DocumentIter has multiple methods to help efficiently deal with nested data types:

• skip_next_value(): Skips over the next value, taking care to handle nested structures properly.
• next_value(): Returns a Value from the iterator.

Implementations

impl<'a, Backing> GenericDocument<'a, Backing>

where Backing: NodeCollection<'a>,

pub fn from_json_bytes(source: &'a [u8]) -> Result<Self, Error>

where Backing: Default,

Parses a JSON payload from source.

This function verifies that json is valid UTF-8 while parsing the JSON.

pub fn from_json_bytes_with_config( source: &'a [u8], config: ParseConfig, ) -> Result<Self, Error>

where Backing: Default,

Parses a JSON payload from source, with the settings from config.

This function verifies that json is valid UTF-8 while parsing the JSON.

pub fn from_json(source: &'a str) -> Result<Self, Error>

where Backing: Default,

Parses a JSON payload from source.

Because the str type guarantees that json is valid UTF-8, no additional unicode checks are performed on unescaped unicode sequences.

Examples found in repository

examples/heapless.rs (line 7)

fn main() {
    // Using a heapless vec, we can parse directly to the stack.
    let doc: HeaplessDocument<'_, 3> =
        HeaplessDocument::from_json(r#"{"hello": "world"}"#).expect("invalid json");
    let mut nodes = doc.into_iter();
    assert_eq!(nodes.next(), Some(Node::Object { length: 1 }));
    assert_eq!(nodes.next(), Some(Node::String(JsonString::from("hello"))));
    assert_eq!(nodes.next(), Some(Node::String(JsonString::from("world"))));

    // When parsing a document too large for the heapless Vec, an error will be
    // returned instead of panicing.
    let error = HeaplessDocument::<3>::from_json("[1, 2, 3, 4]").expect_err("shouldn't have space");
    assert_eq!(error.kind(), &ErrorKind::PaylodTooLarge);
}

pub fn from_json_with_config( source: &'a str, config: ParseConfig, ) -> Result<Self, Error>

where Backing: Default,

Parses a JSON payload from source, with the settings from config.

Because the str type guarantees that json is valid UTF-8, no additional unicode checks are performed on unescaped unicode sequences.

pub fn iter(&self) -> DocumentIter<'_, 'a>

Returns an iterator over the nodes in this document.

Trait Implementations

impl<'a, Backing: Debug> Debug for GenericDocument<'a, Backing>

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

Formats the value using the given formatter.

impl<'a, Backing> From<GenericDocument<'a, Backing>> for Value<'a>

where Backing: NodeCollection<'a>,

Available on crate feature alloc only.

fn from(doc: GenericDocument<'a, Backing>) -> Self

Converts to this type from the input type.

impl<'doc, 'a, Backing> IntoIterator for &'doc GenericDocument<'a, Backing>

where Backing: NodeCollection<'a>,

type IntoIter = DocumentIter<'doc, 'a>

Which kind of iterator are we turning this into?

type Item = Node<'a>

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, Backing: PartialEq> PartialEq for GenericDocument<'a, Backing>

fn eq(&self, other: &GenericDocument<'a, Backing>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, Backing: Eq> Eq for GenericDocument<'a, Backing>

impl<'a, Backing> StructuralPartialEq for GenericDocument<'a, Backing>