Struct Partial

pub struct Partial<I> { /* private fields */ }

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.

• [ErrMode::Incomplete] will report how much more data is needed.
• Parser::complete_err transform [ErrMode::Incomplete] to [ErrMode::Backtrack]

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<'s>(i: &mut Partial<&'s [u8]>) -> PResult<&'s [u8], InputError<Partial<&'s [u8]>>> {
  token::take(4u8).parse_next(i)
}

fn take_complete<'s>(i: &mut &'s [u8]) -> PResult<&'s [u8], InputError<&'s [u8]>> {
  token::take(4u8).parse_next(i)
}

// both parsers will take 4 bytes as expected
assert_eq!(take_partial.parse_peek(Partial::new(&b"abcde"[..])), Ok((Partial::new(&b"e"[..]), &b"abcd"[..])));
assert_eq!(take_complete.parse_peek(&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.parse_peek(Partial::new(&b"abc"[..])), Err(ErrMode::Incomplete(Needed::new(1))));

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

// the alpha0 function takes 0 or more alphabetic characters
fn alpha0_partial<'s>(i: &mut Partial<&'s str>) -> PResult<&'s str, InputError<Partial<&'s str>>> {
  ascii::alpha0.parse_next(i)
}

fn alpha0_complete<'s>(i: &mut &'s str) -> PResult<&'s str, InputError<&'s str>> {
  ascii::alpha0.parse_next(i)
}

// if there's a clear limit to the taken characters, both parsers work the same way
assert_eq!(alpha0_partial.parse_peek(Partial::new("abcd;")), Ok((Partial::new(";"), "abcd")));
assert_eq!(alpha0_complete.parse_peek("abcd;"), Ok((";", "abcd")));

// but when there's no limit, the partial version returns `Incomplete`, because it cannot
// know if more input data should be taken. The whole input could be "abcd;", or
// "abcde;"
assert_eq!(alpha0_partial.parse_peek(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.parse_peek("abcd"), Ok(("", "abcd")));

Implementations

impl<I> Partial<I>

where I: StreamIsPartial,

pub fn new(input: I) -> Self

Create a partial input

pub fn into_inner(self) -> I

Extract the original Stream

Trait Implementations

impl<I> AsBStr for Partial<I>

where I: AsBStr,

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

Casts the input type to a byte slice

impl<I> AsBytes for Partial<I>

where I: AsBytes,

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

Casts the input type to a byte slice

impl<I: Clone> Clone for Partial<I>

fn clone(&self) -> Partial<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 Partial<I>

where I: Compare<T>,

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

Compares self to another value for equality

impl<I: Debug> Debug for Partial<I>

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

Formats the value using the given formatter.

impl<I> Default for Partial<I>

where I: Default + StreamIsPartial,

fn default() -> Self

Returns the “default value” for a type.

impl<I> Deref for Partial<I>

type Target = I

The resulting type after dereferencing.

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

Dereferences the value.

impl<I: Display> Display for Partial<I>

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

Formats the value using the given formatter.

impl<I, T> FindSlice<T> for Partial<I>

where I: FindSlice<T>,

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

Returns the offset of the slice if it is found

impl<I> Location for Partial<I>

where I: Location,

fn location(&self) -> usize

Number of indices input has advanced since start of parsing

impl<I> Offset<<Partial<I> as Stream>::Checkpoint> for Partial<I>

where I: Stream,

fn offset_from(&self, other: &<Partial<I> as Stream>::Checkpoint) -> usize

Offset between the first byte of start and the first byte of selfa

impl<I> Offset for Partial<I>

where I: Stream,

fn offset_from(&self, start: &Self) -> usize

Offset between the first byte of start and the first byte of selfa

impl<I: Ord> Ord for Partial<I>

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<I: PartialEq> PartialEq for Partial<I>

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<I: PartialOrd> PartialOrd for Partial<I>

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<I> SliceLen for Partial<I>

where I: SliceLen,

fn slice_len(&self) -> usize

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

impl<I: Stream> Stream for Partial<I>

type Token = <I as Stream>::Token

The smallest unit being parsed

type Slice = <I as Stream>::Slice

Sequence of Tokens

type IterOffsets = <I as Stream>::IterOffsets

Iterate with the offset from the current location

type Checkpoint = Checkpoint<<I as Stream>::Checkpoint, Partial<I>>

A parse location within the stream

fn iter_offsets(&self) -> Self::IterOffsets

Iterate with the offset from the current location

fn eof_offset(&self) -> usize

Returns the offset to the end of the input

fn next_token(&mut self) -> Option<Self::Token>

Split off the next token from the input

fn offset_for<P>(&self, predicate: P) -> Option<usize>

where P: Fn(Self::Token) -> bool,

Finds the offset of the next matching token

fn offset_at(&self, tokens: usize) -> Result<usize, Needed>

Get the offset for the number of tokens into the stream

fn next_slice(&mut self, offset: usize) -> Self::Slice

Split off a slice of tokens from the input

fn checkpoint(&self) -> Self::Checkpoint

Save the current parse location within the stream

fn reset(&mut self, checkpoint: &Self::Checkpoint)

Revert the stream to a prior Self::Checkpoint

fn raw(&self) -> &dyn Debug

Return the inner-most stream

fn peek_token(&self) -> Option<(Self, Self::Token)>

where Self: Clone,

Split off the next token from the input

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

where Self: Clone,

Split off a slice of tokens from the input

fn finish(&mut self) -> Self::Slice

Advance to the end of the stream

fn peek_finish(&self) -> (Self, Self::Slice)

where Self: Clone,

Advance to the end of the stream

impl<I> StreamIsPartial for Partial<I>

where I: StreamIsPartial,

type PartialState = bool

Whether the stream is currently partial or complete

fn complete(&mut self) -> Self::PartialState

Mark the stream is complete

fn restore_partial(&mut self, state: Self::PartialState)

Restore the stream back to its previous state

fn is_partial_supported() -> bool

Report whether the Stream is can ever be incomplete

fn is_partial(&self) -> bool

Report whether the Stream is currently incomplete

impl<I> UpdateSlice for Partial<I>

where I: UpdateSlice,

fn update_slice(self, inner: Self::Slice) -> Self

Convert an Output type to be used as Stream

impl<I: Copy> Copy for Partial<I>

impl<I: Eq> Eq for Partial<I>

impl<I> StructuralPartialEq for Partial<I>