Struct struson::reader::simple::SimpleJsonReader

pub struct SimpleJsonReader<J: JsonReader> { /* private fields */ }

Available on crate feature experimental only.

JSON reader variant which is easier to use than JsonReader

This JSON reader variant ensures correct usage at compile-time making it easier and less error-prone to use than JsonReader, which validates correct usage at runtime and panics on incorrect usage. However, this comes at the cost of SimpleJsonReader being less flexible to use, and it not offerring all features of JsonReader.

When an error is returned by one of the methods of the reader, the error should be propagated (for example by using Rust’s ? operator), processing should be aborted and the reader should not be used any further.

Examples

// In this example JSON data comes from a string;
// normally it would come from a file or a network connection
let json_reader = SimpleJsonReader::new(r#"["a", "short", "example"]"#.as_bytes());
let mut words = Vec::<String>::new();
json_reader.read_array_items(|item_reader| {
    let word = item_reader.read_string()?;
    words.push(word);
    Ok(())
})?;
assert_eq!(words, vec!["a", "short", "example"]);

Implementations

impl<J: JsonReader> SimpleJsonReader<J>

pub fn from_json_reader(json_reader: J) -> Self

Creates a new SimpleJsonReader from the given JsonReader

The JsonReader acts as delegate which performs the actual JSON reading. It should be positioned at the start of the top-level JSON value and should not have consumed any data yet, otherwise the behavior of the created SimpleJsonReader is unspecified and it may panic.

Examples

let json = r"
    [
        1,
        2,
    ]
    ".as_bytes();

let json_reader = SimpleJsonReader::from_json_reader(
    JsonStreamReader::new_custom(
        json,
        ReaderSettings {
            allow_trailing_comma: true,
            // For all other settings use the default
            ..Default::default()
        },
    )
);

pub fn seek_to(&mut self, path: &JsonPath) -> Result<(), ReaderError>

Seeks to the specified location in the JSON document

Seeks to the specified relative JSON path in the JSON document by skipping all previous values. Once this method returns successfully the reader will be positioned before the last element specified by the path.

For example for the JSON path json_path!["foo", 2] it will start consuming a JSON object, skipping members until it finds one with name “foo”. Then it starts consuming the member value, expecting that it is a JSON array, until right before the array item with (starting at 0) index 2. If multiple members in a JSON object have the same name (for example {"a": 1, "a": 2}) this method will seek to the first occurrence.

Seeking to a specific location can be useful when parts of the processed JSON document are not relevant for the application processing it.

If the structure of the JSON data does not match the path, for example when the JSON data contains an array but the path expects an object, an error is returned.

The seeking behavior of this method is equivalent to read_seeked, but seek_to allows consuming the value afterwards without having to use a closure or separate function (as required by read_seeked), however it is only available for SimpleJsonReader and not generally for the ValueReader trait.

Examples

let mut json_reader = SimpleJsonReader::new(
    r#"{"bar": true, "foo": ["a", "b", "c"]}"#.as_bytes()
);
json_reader.seek_to(&json_path!["foo", 2])?;

// Can now consume the value to which the call seeked to
let value = json_reader.read_string()?;
assert_eq!(value, "c");

impl<R: Read> SimpleJsonReader<JsonStreamReader<R>>

pub fn new(reader: R) -> Self

Creates a new JSON reader

The given reader must provide the JSON data UTF-8 encoded, without leading byte order mark (BOM). Internally this creates a JsonStreamReader which acts as delegate; see its documentation for more information about the parsing behavior and security considerations.

Trait Implementations

impl<J: Debug + JsonReader> Debug for SimpleJsonReader<J>

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

Formats the value using the given formatter.

impl<J: JsonReader> ValueReader<J> for SimpleJsonReader<J>

fn peek_value(&mut self) -> Result<ValueType, ReaderError>

Peeks at the type of the next JSON value, without consuming it

fn read_null(self) -> Result<(), ReaderError>

Consumes a JSON null value

fn read_bool(self) -> Result<bool, ReaderError>

Consumes and returns a JSON boolean value

fn read_str<T>( self, f: impl FnOnce(&str) -> Result<T, Box<dyn Error>> ) -> Result<T, Box<dyn Error>>

Consumes a JSON string value as borrowed str

fn read_string(self) -> Result<String, ReaderError>

Consumes and returns a JSON string value as owned String

fn read_string_with_reader<T>( self, f: impl FnOnce(StringValueReader<'_>) -> Result<T, Box<dyn Error>> ) -> Result<T, Box<dyn Error>>

Consumes a JSON string using a Read

fn read_number<T: FromStr>(self) -> Result<Result<T, T::Err>, ReaderError>

Consumes and returns a JSON number value

fn read_number_as_string(self) -> Result<String, ReaderError>

Consumes and returns the string representation of a JSON number value

fn read_deserialize<'de, D: Deserialize<'de>>( self ) -> Result<D, DeserializerError>

Available on crate feature serde only.

Deserializes a Serde Deserialize from the next value

fn skip_value(self) -> Result<(), ReaderError>

Skips the next JSON value

fn read_array<T>( self, f: impl FnOnce(&mut ArrayReader<'_, J>) -> Result<T, Box<dyn Error>> ) -> Result<T, Box<dyn Error>>

Consumes a JSON array

fn read_object_borrowed_names( self, f: impl FnMut(MemberReader<'_, J>) -> Result<(), Box<dyn Error>> ) -> Result<(), Box<dyn Error>>

Consumes a JSON object and all of its members, reading names as borrowed str

fn read_object_owned_names( self, f: impl FnMut(String, SingleValueReader<'_, J>) -> Result<(), Box<dyn Error>> ) -> Result<(), Box<dyn Error>>

Consumes a JSON object and all of its members, reading names as owned String

fn read_seeked<T>( self, path: &JsonPath, f: impl FnOnce(SingleValueReader<'_, J>) -> Result<T, Box<dyn Error>> ) -> Result<T, Box<dyn Error>>

Seeks to a value and consumes it

fn read_seeked_multi( self, path: &MultiJsonPath, at_least_one_match: bool, f: impl FnMut(SingleValueReader<'_, J>) -> Result<(), Box<dyn Error>> ) -> Result<(), Box<dyn Error>>

Seeks to multiple values and consumes them

fn read_array_items( self, f: impl FnMut(SingleValueReader<'_, J>) -> Result<(), Box<dyn Error>> ) -> Result<(), Box<dyn Error>>

where Self: Sized,

Consumes a JSON array and all of its items