Struct JsonSession

pub struct JsonSession<I: Iterator<Item = u8>> { /* private fields */ }

A pull-based JSON parser which consumes an iterator over bytes and yields a valid sequence of JsonFragmentWithSpan values.

This API allows gathering statistics about the contents of large JSON documents without ever holding the entire document in memory.

JsonSession checks that the input is valid JSON. If an invalid sequence of tokens is detected, JsonSession::next yields an error. As a user of JsonSession, you can rely on the fact that the yielded fragments will always describe a well-formed JSON document, at least the part of the document that has been consumed so far. (To clarify, there is no pre-pass which validates the entire document. Validation happens as you go, so JsonSession::next will happily return fragments as long as it hasn’t arrived at the error yet.)

When the optional feature fallible-iterator is used, JsonSession implements fallible_iterator::FallibleIterator.

Example

use json_session::{JsonSession, JsonFragment, JsonPrimitiveValue};

let input_str = r#"{"key1": 1234, "key2": [true], "key3": "value" }"#;
let expected = &[
    JsonFragment::BeginObject,
    JsonFragment::ObjectProperty(String::from("key1")),
    JsonFragment::PrimitiveValue(JsonPrimitiveValue::Number(1234.0)),
    JsonFragment::ObjectProperty(String::from("key2")),
    JsonFragment::BeginArray,
    JsonFragment::PrimitiveValue(JsonPrimitiveValue::Boolean(true)),
    JsonFragment::EndArray,
    JsonFragment::ObjectProperty(String::from("key3")),
    JsonFragment::PrimitiveValue(JsonPrimitiveValue::String(String::from("value"))),
    JsonFragment::EndObject,
];
let mut session = JsonSession::new(input_str.as_bytes().iter().cloned());
for expected_fragment in expected {
    let fragment = session.next().unwrap().unwrap().fragment;
    assert_eq!(fragment, *expected_fragment);
}
assert!(session.next().unwrap().is_none());

Implementations

impl<I: Iterator<Item = u8>> JsonSession<I>

pub fn new(it: I) -> Self

Create a new JsonSession from an iterator over bytes.

pub fn next(&mut self) -> JsonParseResult<Option<JsonFragmentWithSpan>>

Get the next JsonFragmentWithSpan.

Returns:

• Ok(Some(...)) in the regular case, with the next fragment.
• Ok(None) if the JSON document is complete and the end of the input has been reached.
• Err(...) if a invalid JSON is detected.