Struct nom8::input::Streaming

pub struct Streaming<I>(pub I);

Mark the input as a partial buffer for streaming input.

Complete input means that we already have all of the data. This will be the common case with small files that can be read entirely to memory.

In contrast, streaming input assumes that we might not have all of the data. This can happen with some network protocol or large file parsers, where the input buffer can be full and need to be resized or refilled.

• Err::Incomplete will report how much more data is needed.
• Parser::complete transform Err::Incomplete to Err::Error

See also InputIsStreaming to tell whether the input supports complete or streaming parsing.

Example

Here is how it works in practice:

use nom8::{IResult, Err, Needed, error::{Error, ErrorKind}, bytes, character, input::Streaming};

fn take_streaming(i: Streaming<&[u8]>) -> IResult<Streaming<&[u8]>, &[u8]> {
  bytes::take(4u8)(i)
}

fn take_complete(i: &[u8]) -> IResult<&[u8], &[u8]> {
  bytes::take(4u8)(i)
}

// both parsers will take 4 bytes as expected
assert_eq!(take_streaming(Streaming(&b"abcde"[..])), Ok((Streaming(&b"e"[..]), &b"abcd"[..])));
assert_eq!(take_complete(&b"abcde"[..]), Ok((&b"e"[..], &b"abcd"[..])));

// if the input is smaller than 4 bytes, the streaming parser
// will return `Incomplete` to indicate that we need more data
assert_eq!(take_streaming(Streaming(&b"abc"[..])), Err(Err::Incomplete(Needed::new(1))));

// but the complete parser will return an error
assert_eq!(take_complete(&b"abc"[..]), Err(Err::Error(Error::new(&b"abc"[..], ErrorKind::Eof))));

// the alpha0 function recognizes 0 or more alphabetic characters
fn alpha0_streaming(i: Streaming<&str>) -> IResult<Streaming<&str>, &str> {
  character::alpha0(i)
}

fn alpha0_complete(i: &str) -> IResult<&str, &str> {
  character::alpha0(i)
}

// if there's a clear limit to the recognized characters, both parsers work the same way
assert_eq!(alpha0_streaming(Streaming("abcd;")), Ok((Streaming(";"), "abcd")));
assert_eq!(alpha0_complete("abcd;"), Ok((";", "abcd")));

// but when there's no limit, the streaming version returns `Incomplete`, because it cannot
// know if more input data should be recognized. The whole input could be "abcd;", or
// "abcde;"
assert_eq!(alpha0_streaming(Streaming("abcd")), Err(Err::Incomplete(Needed::new(1))));

// while the complete version knows that all of the data is there
assert_eq!(alpha0_complete("abcd"), Ok(("", "abcd")));

Tuple Fields

0: I

Implementations

impl<I> Streaming<I>

pub fn into_complete(self) -> I

Convert to complete counterpart

Trait Implementations

impl<I> AsBytes for Streaming<I>where I: AsBytes,

fn as_bytes(&self) -> &[u8]

Casts the input type to a byte slice

impl<I: Clone> Clone for Streaming<I>

fn clone(&self) -> Streaming<I>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<I, T> Compare<T> for Streaming<I>where I: Compare<T>,

fn compare(&self, t: T) -> CompareResult

Compares self to another value for equality

fn compare_no_case(&self, t: T) -> CompareResult

Compares self to another value for equality independently of the case.

impl<I: Debug> Debug for Streaming<I>

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

Formats the value using the given formatter.

impl<I: Default> Default for Streaming<I>

fn default() -> Streaming<I>

Returns the “default value” for a type.

impl<I> Deref for Streaming<I>

type Target = I

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<I> ExtendInto for Streaming<I>where I: ExtendInto,

type Item = <I as ExtendInto>::Item

The current input type is a sequence of that Item type.

type Extender = <I as ExtendInto>::Extender

The type that will be produced

fn new_builder(&self) -> Self::Extender

Create a new Extend of the correct type

fn extend_into(&self, acc: &mut Self::Extender)

Accumulate the input into an accumulator

impl<I, T> FindSubstring<T> for Streaming<I>where I: FindSubstring<T>,

fn find_substring(&self, substr: T) -> Option<usize>

Returns the byte position of the substring if it is found

impl<I, T> FindToken<T> for Streaming<I>where I: FindToken<T>,

fn find_token(&self, token: T) -> bool

Returns true if self contains the token

impl<I> HexDisplay for Streaming<I>where I: HexDisplay,

fn to_hex(&self, chunk_size: usize) -> String

Converts the value of self to a hex dump, returning the owned String.

fn to_hex_from(&self, chunk_size: usize, from: usize) -> String

Converts the value of self to a hex dump beginning at from address, returning the owned String.

impl<I> InputIsStreaming<true> for Streaming<I>where I: InputIsStreaming<false>,

type Complete = I

Complete counterpart

type Streaming = Streaming<I>

Streaming counterpart

fn into_complete(self) -> Self::Complete

Convert to complete counterpart

fn into_streaming(self) -> Self::Streaming

Convert to streaming counterpart

impl<I> InputIter for Streaming<I>where I: InputIter,

type Item = <I as InputIter>::Item

The current input type is a sequence of that Item type.

type Iter = <I as InputIter>::Iter

An iterator over the input type, producing the item and its position for use with Slice. If we’re iterating over &str, the position corresponds to the byte index of the character

type IterElem = <I as InputIter>::IterElem

An iterator over the input type, producing the item

fn iter_indices(&self) -> Self::Iter

Returns an iterator over the elements and their byte offsets

fn iter_elements(&self) -> Self::IterElem

Returns an iterator over the elements

fn position<P>(&self, predicate: P) -> Option<usize>where P: Fn(Self::Item) -> bool,

Finds the byte position of the element

fn slice_index(&self, count: usize) -> Result<usize, Needed>

Get the byte offset from the element’s position in the stream

impl<I> InputLength for Streaming<I>where I: InputLength,

fn input_len(&self) -> usize

Calculates the input length, as indicated by its name, and the name of the trait itself

impl<I> InputTake for Streaming<I>where I: InputTake,

fn take(&self, count: usize) -> Self

Returns a slice of count bytes. panics if count > length

fn take_split(&self, count: usize) -> (Self, Self)

Split the stream at the count byte offset. panics if count > length

impl<I> InputTakeAtPosition for Streaming<I>where I: InputTakeAtPosition,

type Item = <I as InputTakeAtPosition>::Item

The current input type is a sequence of that Item type.

fn split_at_position_complete<P, E>( &self, predicate: P ) -> IResult<Self, Self, E>where P: Fn(Self::Item) -> bool, E: ParseError<Self>,

Looks for the first element of the input type for which the condition returns true, and returns the input up to this position.

fn split_at_position_streaming<P, E>( &self, predicate: P ) -> IResult<Self, Self, E>where P: Fn(Self::Item) -> bool, E: ParseError<Self>,

Looks for the first element of the input type for which the condition returns true, and returns the input up to this position.

fn split_at_position1_streaming<P, E>( &self, predicate: P, kind: ErrorKind ) -> IResult<Self, Self, E>where P: Fn(Self::Item) -> bool, E: ParseError<Self>,

Looks for the first element of the input type for which the condition returns true and returns the input up to this position.

fn split_at_position1_complete<P, E>( &self, predicate: P, kind: ErrorKind ) -> IResult<Self, Self, E>where P: Fn(Self::Item) -> bool, E: ParseError<Self>,

Looks for the first element of the input type for which the condition returns true and returns the input up to this position.

impl<I> IntoOutput for Streaming<I>where I: IntoOutput,

type Output = <I as IntoOutput>::Output

Output type

fn into_output(self) -> Self::Output

Convert an Input into an appropriate Output type

fn merge_output(self, inner: Self::Output) -> Self

Convert an Output type to be used as Input

impl<I> Location for Streaming<I>where I: Location,

fn location(&self) -> usize

Number of indices input has advanced since start of parsing

impl<I> Offset for Streaming<I>where I: Offset,

fn offset(&self, second: &Self) -> usize

Offset between the first byte of self and the first byte of the argument

impl<I: Ord> Ord for Streaming<I>

fn cmp(&self, other: &Streaming<I>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl<I, R> ParseTo<R> for Streaming<I>where I: ParseTo<R>,

fn parse_to(&self) -> Option<R>

Succeeds if parse() succeeded. The byte slice implementation will first convert it to a &str, then apply the parse() function

impl<I: PartialEq> PartialEq<Streaming<I>> for Streaming<I>

fn eq(&self, other: &Streaming<I>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<I: PartialOrd> PartialOrd<Streaming<I>> for Streaming<I>

fn partial_cmp(&self, other: &Streaming<I>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<I, R> Slice<R> for Streaming<I>where I: Slice<R>,

fn slice(&self, range: R) -> Self

Slices self according to the range argument

impl<I: Copy> Copy for Streaming<I>

impl<I: Eq> Eq for Streaming<I>

impl<I> StructuralEq for Streaming<I>

impl<I> StructuralPartialEq for Streaming<I>