pub struct Reader<'a> { /* private fields */ }Expand description
A pull parser: reads a document one Event at a time, building nothing.
The reader is the layer every parse in this crate goes through: it checks
the full RFC 8259 grammar and every budget in Limits as it goes, with
the same errors and byte offsets as parse. Use it to pick
a few fields out of a large document, to stream a document’s contents
somewhere without holding a tree, or to keep part of a message as raw text
to be read later (read_raw).
The reader works over a complete document held in memory, and borrows
strings and numbers from it exactly as parse does.
Reading is iterative: depth costs one byte of reader state per level, never
stack. The reader does not look for duplicate keys, which needs memory
proportional to an object’s size; read_value applies
the configured DuplicateKeys policy to the values it builds.
After an error the reader is finished: every later call returns the same error.
§Examples
Read a JSON-RPC envelope, keeping params as raw text for later:
use jsonx_lib::{Event, Reader};
let message = r#"{"jsonrpc": "2.0", "id": 4, "method": "hover", "params": {"line": 3}}"#;
let mut reader = Reader::new(message);
let (mut method, mut params) = (None, None);
assert_eq!(reader.next_event()?, Some(Event::StartObject));
while let Some(Event::Key(key)) = reader.next_event()? {
match &*key {
"method" => method = reader.read_value()?,
"params" => params = reader.read_raw()?,
_ => { let _skipped = reader.read_raw()?; }
}
}
reader.finish()?; // the rest of the document must be valid too
assert_eq!(method.as_ref().and_then(|m| m.as_str()), Some("hover"));
assert_eq!(params, Some(r#"{"line": 3}"#));Implementations§
Source§impl<'a> Reader<'a>
impl<'a> Reader<'a>
Sourcepub fn next_event(&mut self) -> Result<Option<Event<'a>>, Error>
pub fn next_event(&mut self) -> Result<Option<Event<'a>>, Error>
Reads the next event, or Ok(None) once the document’s value is
complete and nothing but whitespace follows it.
§Errors
The first syntax error or exceeded budget, at its byte offset (see
Error). Once an error is returned, every later call returns it too.
§Examples
use jsonx_lib::{ErrorKind, Event, Reader};
let mut r = Reader::new("[1,]");
assert_eq!(r.next_event()?, Some(Event::StartArray));
assert!(r.next_event()?.is_some()); // 1
let err = r.next_event().unwrap_err();
assert_eq!((err.kind(), err.offset()), (ErrorKind::TrailingComma, 3));Sourcepub fn read_raw(&mut self) -> Result<Option<&'a str>, Error>
pub fn read_raw(&mut self) -> Result<Option<&'a str>, Error>
Reads the next value whole and returns its exact source text, without decoding or allocating anything.
Call it where a value comes next: at the start, after a Key,
or between array items. The value is fully validated. If no value comes
next (the current array or object ends, or the document already ended),
returns Ok(None) and consumes nothing, so the next
next_event returns the end event as usual. Calling
it where a key comes next also returns Ok(None).
The text is a slice of the input: it can be stored, compared, or parsed
later, as serde_json’s RawValue is used.
§Errors
As next_event, for any error inside the value.
§Examples
use jsonx_lib::{Event, Reader};
let mut r = Reader::new(r#"[{"deep": [1, 2]}, "x"]"#);
assert_eq!(r.next_event()?, Some(Event::StartArray));
assert_eq!(r.read_raw()?, Some(r#"{"deep": [1, 2]}"#));
assert_eq!(r.read_raw()?, Some(r#""x""#));
assert_eq!(r.read_raw()?, None); // the array ends here
assert_eq!(r.next_event()?, Some(Event::EndArray));Sourcepub fn read_value(&mut self) -> Result<Option<Value<'a>>, Error>
pub fn read_value(&mut self) -> Result<Option<Value<'a>>, Error>
Reads the next value whole and builds it as a Value, applying the
reader’s DuplicateKeys policy.
Positioning is as for read_raw: Ok(None), with
nothing consumed, when no value comes next.
§Errors
As next_event, plus ErrorKind::DuplicateKey
under DuplicateKeys::Error.
§Examples
use jsonx_lib::{Event, Reader};
let mut r = Reader::new(r#"{"skip": [0], "keep": {"a": 1}}"#);
r.next_event()?; // {
r.next_event()?; // "skip"
r.read_raw()?;
assert_eq!(r.next_event()?, Some(Event::Key("keep".into())));
let keep = r.read_value()?.unwrap_or_default();
assert_eq!(keep["a"], 1);Sourcepub fn finish(self) -> Result<(), Error>
pub fn finish(self) -> Result<(), Error>
Reads to the end of the document, checking that the rest of it is valid and that nothing but whitespace follows its value.
§Errors
The first error in the rest of the document.
§Examples
use jsonx_lib::{ErrorKind, Event, Reader};
let mut r = Reader::new(r#"{"id": 1, "x": [} "#);
assert_eq!(r.next_event()?, Some(Event::StartObject));
let err = r.finish().unwrap_err();
assert_eq!((err.kind(), err.offset()), (ErrorKind::ExpectedValue, 16));Sourcepub fn depth(&self) -> usize
pub fn depth(&self) -> usize
The number of arrays and objects open at this point.
§Examples
let mut r = jsonx_lib::Reader::new("[[]]");
r.next_event()?;
r.next_event()?;
assert_eq!(r.depth(), 2);Sourcepub fn offset(&self) -> usize
pub fn offset(&self) -> usize
The byte offset just past the input consumed so far.
§Examples
let mut r = jsonx_lib::Reader::new("[10, 20]");
r.next_event()?;
r.next_event()?;
assert_eq!(r.offset(), 3);Sourcepub fn event_offset(&self) -> usize
pub fn event_offset(&self) -> usize
The byte offset where the most recent event’s token began: the quote of a key or string, the first byte of a number or literal, the bracket or brace of a start or end event. Useful for pointing a diagnostic of your own at the value it is about.
§Examples
let mut r = jsonx_lib::Reader::new(r#"{ "a" : 1 }"#);
r.next_event()?;
r.next_event()?;
assert_eq!(r.event_offset(), 2); // the key's opening quote
r.next_event()?;
assert_eq!(r.event_offset(), 8); // the numberTrait Implementations§
impl FusedIterator for Reader<'_>
Source§impl<'a> Iterator for Reader<'a>
impl<'a> Iterator for Reader<'a>
Source§fn next(&mut self) -> Option<Self::Item>
fn next(&mut self) -> Option<Self::Item>
The next event; after the end or an error, None. An error is yielded
once.
Source§fn next_chunk<const N: usize>(
&mut self,
) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>where
Self: Sized,
fn next_chunk<const N: usize>(
&mut self,
) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>where
Self: Sized,
iter_next_chunk)N values. Read more1.0.0 (const: unstable) · Source§fn size_hint(&self) -> (usize, Option<usize>)
fn size_hint(&self) -> (usize, Option<usize>)
1.0.0 (const: unstable) · Source§fn count(self) -> usizewhere
Self: Sized,
fn count(self) -> usizewhere
Self: Sized,
1.0.0 (const: unstable) · Source§fn last(self) -> Option<Self::Item>where
Self: Sized,
fn last(self) -> Option<Self::Item>where
Self: Sized,
Source§fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
iter_advance_by)n elements. Read more1.0.0 (const: unstable) · Source§fn nth(&mut self, n: usize) -> Option<Self::Item>
fn nth(&mut self, n: usize) -> Option<Self::Item>
nth element of the iterator. Read more1.28.0 (const: unstable) · Source§fn step_by(self, step: usize) -> StepBy<Self> ⓘwhere
Self: Sized,
fn step_by(self, step: usize) -> StepBy<Self> ⓘwhere
Self: Sized,
1.0.0 (const: unstable) · Source§fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter> ⓘ
fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter> ⓘ
1.0.0 (const: unstable) · Source§fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter> ⓘwhere
Self: Sized,
U: IntoIterator,
fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter> ⓘwhere
Self: Sized,
U: IntoIterator,
Source§fn intersperse(self, separator: Self::Item) -> Intersperse<Self> ⓘ
fn intersperse(self, separator: Self::Item) -> Intersperse<Self> ⓘ
iter_intersperse)separator between items
of the original iterator. Read moreSource§fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G> ⓘ
fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G> ⓘ
iter_intersperse)separator
between items of the original iterator. Read more1.0.0 (const: unstable) · Source§fn map<B, F>(self, f: F) -> Map<Self, F> ⓘ
fn map<B, F>(self, f: F) -> Map<Self, F> ⓘ
1.21.0 (const: unstable) · Source§fn for_each<F>(self, f: F)
fn for_each<F>(self, f: F)
1.0.0 (const: unstable) · Source§fn filter<P>(self, predicate: P) -> Filter<Self, P> ⓘ
fn filter<P>(self, predicate: P) -> Filter<Self, P> ⓘ
1.0.0 (const: unstable) · Source§fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> ⓘ
fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> ⓘ
1.0.0 (const: unstable) · Source§fn enumerate(self) -> Enumerate<Self> ⓘwhere
Self: Sized,
fn enumerate(self) -> Enumerate<Self> ⓘwhere
Self: Sized,
1.0.0 (const: unstable) · Source§fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> ⓘ
fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> ⓘ
1.57.0 (const: unstable) · Source§fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P> ⓘ
fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P> ⓘ
1.0.0 (const: unstable) · Source§fn skip(self, n: usize) -> Skip<Self> ⓘwhere
Self: Sized,
fn skip(self, n: usize) -> Skip<Self> ⓘwhere
Self: Sized,
n elements. Read more1.0.0 (const: unstable) · Source§fn take(self, n: usize) -> Take<Self> ⓘwhere
Self: Sized,
fn take(self, n: usize) -> Take<Self> ⓘwhere
Self: Sized,
n elements, or fewer
if the underlying iterator ends sooner. Read more1.0.0 (const: unstable) · Source§fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F> ⓘ
fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F> ⓘ
1.0.0 (const: unstable) · Source§fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> ⓘ
fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> ⓘ
1.29.0 (const: unstable) · Source§fn flatten(self) -> Flatten<Self> ⓘ
fn flatten(self) -> Flatten<Self> ⓘ
Source§fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N> ⓘ
fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N> ⓘ
iter_map_windows)f for each contiguous window of size N over
self and returns an iterator over the outputs of f. Like slice::windows(),
the windows during mapping overlap as well. Read more1.0.0 (const: unstable) · Source§fn inspect<F>(self, f: F) -> Inspect<Self, F> ⓘ
fn inspect<F>(self, f: F) -> Inspect<Self, F> ⓘ
1.0.0 (const: unstable) · Source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
Iterator. Read more1.0.0 (const: unstable) · Source§fn collect<B>(self) -> B
fn collect<B>(self) -> B
Source§fn try_collect<B>(
&mut self,
) -> <<Self::Item as Try>::Residual as Residual<B>>::TryType
fn try_collect<B>( &mut self, ) -> <<Self::Item as Try>::Residual as Residual<B>>::TryType
iterator_try_collect)Source§fn collect_into<E>(self, collection: &mut E) -> &mut E
fn collect_into<E>(self, collection: &mut E) -> &mut E
iter_collect_into)1.0.0 (const: unstable) · Source§fn partition<B, F>(self, f: F) -> (B, B)
fn partition<B, F>(self, f: F) -> (B, B)
Source§fn is_partitioned<P>(self, predicate: P) -> bool
fn is_partitioned<P>(self, predicate: P) -> bool
iter_is_partitioned)true precede all those that return false. Read more1.27.0 (const: unstable) · Source§fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R
fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R
1.27.0 (const: unstable) · Source§fn try_for_each<F, R>(&mut self, f: F) -> R
fn try_for_each<F, R>(&mut self, f: F) -> R
1.0.0 (const: unstable) · Source§fn fold<B, F>(self, init: B, f: F) -> B
fn fold<B, F>(self, init: B, f: F) -> B
1.51.0 (const: unstable) · Source§fn reduce<F>(self, f: F) -> Option<Self::Item>
fn reduce<F>(self, f: F) -> Option<Self::Item>
Source§fn try_reduce<R>(
&mut self,
f: impl FnMut(Self::Item, Self::Item) -> R,
) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
fn try_reduce<R>( &mut self, f: impl FnMut(Self::Item, Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
iterator_try_reduce)1.0.0 (const: unstable) · Source§fn all<F>(&mut self, f: F) -> bool
fn all<F>(&mut self, f: F) -> bool
1.0.0 (const: unstable) · Source§fn any<F>(&mut self, f: F) -> bool
fn any<F>(&mut self, f: F) -> bool
1.0.0 (const: unstable) · Source§fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
1.30.0 (const: unstable) · Source§fn find_map<B, F>(&mut self, f: F) -> Option<B>
fn find_map<B, F>(&mut self, f: F) -> Option<B>
Source§fn try_find<R>(
&mut self,
f: impl FnMut(&Self::Item) -> R,
) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType
fn try_find<R>( &mut self, f: impl FnMut(&Self::Item) -> R, ) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType
try_find)1.0.0 (const: unstable) · Source§fn position<P>(&mut self, predicate: P) -> Option<usize>
fn position<P>(&mut self, predicate: P) -> Option<usize>
1.0.0 (const: unstable) · Source§fn max(self) -> Option<Self::Item>
fn max(self) -> Option<Self::Item>
1.0.0 (const: unstable) · Source§fn min(self) -> Option<Self::Item>
fn min(self) -> Option<Self::Item>
1.6.0 (const: unstable) · Source§fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>
fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>
1.15.0 (const: unstable) · Source§fn max_by<F>(self, compare: F) -> Option<Self::Item>
fn max_by<F>(self, compare: F) -> Option<Self::Item>
1.6.0 (const: unstable) · Source§fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>
fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>
1.15.0 (const: unstable) · Source§fn min_by<F>(self, compare: F) -> Option<Self::Item>
fn min_by<F>(self, compare: F) -> Option<Self::Item>
1.0.0 (const: unstable) · Source§fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
1.36.0 (const: unstable) · Source§fn copied<'a, T>(self) -> Copied<Self> ⓘ
fn copied<'a, T>(self) -> Copied<Self> ⓘ
1.0.0 (const: unstable) · Source§fn cycle(self) -> Cycle<Self> ⓘ
fn cycle(self) -> Cycle<Self> ⓘ
Source§fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N> ⓘwhere
Self: Sized,
fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N> ⓘwhere
Self: Sized,
iter_array_chunks)N elements of the iterator at a time. Read more1.11.0 (const: unstable) · Source§fn product<P>(self) -> P
fn product<P>(self) -> P
Source§fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering
fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering
iter_order_by)Iterator with those
of another with respect to the specified comparison function. Read more1.5.0 (const: unstable) · Source§fn partial_cmp<I>(self, other: I) -> Option<Ordering>
fn partial_cmp<I>(self, other: I) -> Option<Ordering>
PartialOrd elements of
this Iterator with those of another. The comparison works like short-circuit
evaluation, returning a result without comparing the remaining elements.
As soon as an order can be determined, the evaluation stops and a result is returned. Read moreSource§fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>where
Self: Sized,
I: IntoIterator,
F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,
fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>where
Self: Sized,
I: IntoIterator,
F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,
iter_order_by)Iterator with those
of another with respect to the specified comparison function. Read moreSource§fn eq_by<I, F>(self, other: I, eq: F) -> bool
fn eq_by<I, F>(self, other: I, eq: F) -> bool
iter_order_by)1.5.0 (const: unstable) · Source§fn lt<I>(self, other: I) -> bool
fn lt<I>(self, other: I) -> bool
Iterator are lexicographically
less than those of another. Read more1.5.0 (const: unstable) · Source§fn le<I>(self, other: I) -> bool
fn le<I>(self, other: I) -> bool
Iterator are lexicographically
less or equal to those of another. Read more1.5.0 (const: unstable) · Source§fn gt<I>(self, other: I) -> bool
fn gt<I>(self, other: I) -> bool
Iterator are lexicographically
greater than those of another. Read more1.5.0 (const: unstable) · Source§fn ge<I>(self, other: I) -> bool
fn ge<I>(self, other: I) -> bool
Iterator are lexicographically
greater than or equal to those of another. Read more