Struct winnow::stream::Partial

source ·
pub struct Partial<I> { /* private fields */ }
Expand description

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.

See also StreamIsPartial to tell whether the input supports complete or partial parsing.

See also [Special Topics: Parsing Partial Input][crate::_topic::partial].

Example

Here is how it works in practice:


fn take_partial(i: Partial<&[u8]>) -> IResult<Partial<&[u8]>, &[u8]> {
  bytes::take(4u8).parse_next(i)
}

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

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

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

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

// the alpha0 function recognizes 0 or more alphabetic characters
fn alpha0_partial(i: Partial<&str>) -> IResult<Partial<&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_partial(Partial::new("abcd;")), Ok((Partial::new(";"), "abcd")));
assert_eq!(alpha0_complete("abcd;"), Ok((";", "abcd")));

// but when there's no limit, the partial 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_partial(Partial::new("abcd")), Err(ErrMode::Incomplete(Needed::new(1))));

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

Implementations§

Create a partial input

Extract the original Stream

Trait Implementations§

Casts the input type to a byte slice
Casts the input type to a byte slice
Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Compares self to another value for equality
Compares self to another value for equality independently of the case. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
The resulting type after dereferencing.
Dereferences the value.
Formats the value using the given formatter. Read more
Returns the offset of the slice if it is found
Number of indices input has advanced since start of parsing
Offset between the first byte of self and the first byte of the argument
This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Calculates the input length, as indicated by its name, and the name of the trait itself
The smallest unit being parsed Read more
Sequence of Tokens Read more
Iterate with the offset from the current location
Iterate with the offset from the current location
Returns the offaet to the end of the input
Split off the next token from the input
Finds the offset of the next matching token
Get the offset for the number of tokens into the stream Read more
Split off a slice of tokens from the input Read more
Whether the stream is currently partial or complete
Mark the stream is complete
Restore the stream back to its previous state
Report whether the Stream is can ever be incomplete
Report whether the Stream is currently incomplete
Convert an Output type to be used as Stream

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.