Trait ParseIterator

pub trait ParseIterator<'s> {
    type PointInTime: PointInTime;

    // Required methods
    fn slice(&self) -> &'s [u8] ;
    fn pit(&self) -> Self::PointInTime;
    fn restore_pit(&mut self, pit: Self::PointInTime);
    fn advance(&mut self) -> Option<()>;
    fn recorder(&self) -> Option<&Recorder>;
    unsafe fn is_valid_utf8() -> bool;

    // Provided methods
    fn advance_if<F>(&mut self, advance_if: F) -> Option<bool>
       where F: FnOnce(&u8) -> bool { ... }
    fn byte(&self) -> Option<u8> { ... }
    fn next(&mut self) -> Option<u8> { ... }
    fn next_if<F>(&mut self, next_if: F) -> Option<u8>
       where F: FnOnce(&u8) -> bool { ... }
    fn peek(&mut self) -> Option<u8> { ... }
    fn peek_len(&mut self, len: usize) -> Option<&'s [u8]>
       where Self: Sized { ... }
    fn peek_at(&mut self, pos: usize) -> Option<u8> { ... }
    fn ignore_byte(&mut self, byte: u8) -> IgnoreByte<'_, Self>
       where Self: Sized { ... }
    fn while_byte_fn<F>(&mut self, f: F) -> WhileByteFn<'_, Self, F>
       where Self: Sized,
             F: Fn(&u8) -> bool { ... }
    fn consume(&mut self) -> &mut Self { ... }
    fn consume_and_count(&mut self) -> usize { ... }
    fn consume_len(&mut self, len: usize) -> Result<&mut Self, usize> { ... }
    fn consume_at_least(&mut self, len: usize) -> Result<&mut Self, usize> { ... }
    fn consume_at_least_and_count(&mut self, len: usize) -> Result<usize, usize> { ... }
    fn consume_while_byte_fn<F>(&mut self, f: F) -> &mut Self
       where Self: Sized,
             F: Fn(&u8) -> bool { ... }
    fn consume_while_byte(&mut self, byte: u8) -> &mut Self
       where Self: Sized { ... }
    fn split_on_byte(&mut self, byte: u8) -> SplitOnByte<'_, Self>
       where Self: Sized { ... }
    fn count_byte(&mut self, byte: u8) -> usize
       where Self: Sized { ... }
    fn record(&mut self) -> RecordIter<'_, Self>
       where Self: Sized { ... }
    fn to_slice(&self) -> &'s [u8]  { ... }
    unsafe fn to_str_unchecked(&self) -> &'s str { ... }
    fn to_str(&self) -> &'s str { ... }
    fn try_to_str(&self) -> Result<&'s str, Utf8Error> { ... }
    fn consume_to_slice(&mut self) -> &'s [u8]  { ... }
    unsafe fn consume_to_str_unchecked(&mut self) -> &'s str { ... }
    fn consume_to_str(&mut self) -> &'s str { ... }
    fn consume_try_to_str(&mut self) -> Result<&'s str, Utf8Error> { ... }
    fn expect_byte_fn<F>(&mut self, f: F) -> Result<&mut Self, Option<u8>>
       where F: Fn(u8) -> bool { ... }
    fn expect_byte(&mut self, byte: u8) -> Result<&mut Self, Option<u8>> { ... }
    fn expect_none(&mut self) -> Result<&mut Self, u8> { ... }
    fn stop(&mut self) -> Stop<'_, Self>
       where Self: Sized { ... }
}

The main trait of this crate.

This trait allows to parse a slice or a str more easely.

This trait is lazy, if something should happen you need to consume it.
For example, to_str only works if you call record and consume first.

Required Associated Types

type PointInTime: PointInTime

The type that is used to store information about the current position.

Required Methods

fn slice(&self) -> &'s [u8]

Returns the full underlying slice.

fn pit(&self) -> Self::PointInTime

Returns the current position. Should be used in combination with restore_pit.

fn restore_pit(&mut self, pit: Self::PointInTime)

Restore to a given position.

Warning

Only call this method with a pit that was received from this instance.

fn advance(&mut self) -> Option<()>

Advances the internal position.

fn recorder(&self) -> Option<&Recorder>

Returns a Recorder if recording was started.

unsafe fn is_valid_utf8() -> bool

Safety

Returning false is always safe. If you return true the entire underlying slice must be valid utf8.

Provided Methods

fn advance_if<F>(&mut self, advance_if: F) -> Option<bool>

where F: FnOnce(&u8) -> bool,

Advances if advance_if returns true. Returns None if the iterator is empty.

fn byte(&self) -> Option<u8>

Returns the current byte if it exists.

fn next(&mut self) -> Option<u8>

Returns the next byte if it exists and advances the internal position.

fn next_if<F>(&mut self, next_if: F) -> Option<u8>

where F: FnOnce(&u8) -> bool,

Advances one if next_if returns true. Returns None if did not advance.

fn peek(&mut self) -> Option<u8>

Returns the next byte without advancing the internal position.

fn peek_len(&mut self, len: usize) -> Option<&'s [u8]>

where Self: Sized,

Returns the next x bytes without advancing the internal position.

fn peek_at(&mut self, pos: usize) -> Option<u8>

Tries to get the byte at the given position, without advancing.

fn ignore_byte(&mut self, byte: u8) -> IgnoreByte<'_, Self>

where Self: Sized,

Skips a given byte when calling next.

Warning

If you later call to_slice or a similar methods the skipped byte will still be returned.

Example

let mut parser = Parser::new(b"abc");
let mut parser = parser.ignore_byte(b'b');
assert_eq!(b'a', parser.next().unwrap());
assert_eq!(b'c', parser.next().unwrap());

fn while_byte_fn<F>(&mut self, f: F) -> WhileByteFn<'_, Self, F>

where Self: Sized, F: Fn(&u8) -> bool,

Advances while the function returns true.

fn consume(&mut self) -> &mut Self

Consumes until the iterator is empty. Meaning that advance returns None.

fn consume_and_count(&mut self) -> usize

Consumes until the iterator is empty, and returns how many times advance got called.

fn consume_len(&mut self, len: usize) -> Result<&mut Self, usize>

Consumes a given length. Returns how much was consumed if could not consume all.

fn consume_at_least(&mut self, len: usize) -> Result<&mut Self, usize>

Consumes until the iterator is empty. Returns Err(len) if could not consume len.

fn consume_at_least_and_count(&mut self, len: usize) -> Result<usize, usize>

Consumes until the iterator is empty, returning how much was consumed. Returns Err(len) if could not consume len.

fn consume_while_byte_fn<F>(&mut self, f: F) -> &mut Self

where Self: Sized, F: Fn(&u8) -> bool,

Consumes while the function returns true.

fn consume_while_byte(&mut self, byte: u8) -> &mut Self

where Self: Sized,

Consumes while a give byte is returned.

fn split_on_byte(&mut self, byte: u8) -> SplitOnByte<'_, Self>

where Self: Sized,

Splits the iterator at a given byte.

Example

let mut parser = StrParser::new("Hello World!");
let mut splitter = parser.split_on_byte(b' ');

let hello = splitter.next().unwrap()
	.record().consume_to_str();
let world = splitter.next().unwrap()
	.record().consume_to_str();

assert_eq!(hello, "Hello");
assert_eq!(world, "World!");
assert!(splitter.next().is_none());

fn count_byte(&mut self, byte: u8) -> usize

where Self: Sized,

fn record(&mut self) -> RecordIter<'_, Self>

where Self: Sized,

Starts a new Recorder which starts recording at this position.

fn to_slice(&self) -> &'s [u8]

Returns a slice from the start of recording until now.

Panics

If not called in context of a recorder. Meaning before calling record.

unsafe fn to_str_unchecked(&self) -> &'s str

Returns a str from the start of recording until the current position without checking if the data is valid utf8.

Panics

Panics if not called after record gets called.

Safety

This function is safe if Self::is_valid_utf8 returns true.

fn to_str(&self) -> &'s str

Returns a str from the start of recording until the current position.

Example

let str_from_slice = Parser::new(b"abc")
	.record()
	.consume()
	.to_str();
assert_eq!(str_from_slice, "abc");

let str_from_str = StrParser::new("abc")
	.record()
	.consume()
	.to_str();
assert_eq!(str_from_str, "abc");

Panics

Panics if not called after record was called. Or if invalid utf8 is present.

fn try_to_str(&self) -> Result<&'s str, Utf8Error>

Returns a str from the start of recording until the current position.

Example

let str_from_slice = Parser::new(b"abc")
	.record()
	.consume()
	.try_to_str().expect("slice is not valid utf8");
assert_eq!(str_from_slice, "abc");

let str_from_str = StrParser::new("abc")
	.record()
	.consume()
		// can never return Err
	.try_to_str().unwrap();
assert_eq!(str_from_str, "abc");

Panics

Panics if not called after record was called.

fn consume_to_slice(&mut self) -> &'s [u8]

Consumes the iterator and then returns a slice from the start of recording until the current position.

Panics

Panics if not called after record was called.

unsafe fn consume_to_str_unchecked(&mut self) -> &'s str

Consumes the iterator and then returns a str from the start of recording until the current position. Without checking if the underlying data is valid utf8.

Panics

Panics if not called after record was called.

fn consume_to_str(&mut self) -> &'s str

Consumes the iterator and then returns a str from the start of recording until the current position.

Panics

Panics if not called after record was called or if the data contains invalid utf8.

fn consume_try_to_str(&mut self) -> Result<&'s str, Utf8Error>

Consumes the iterator and then returns a str from the start of recording until the current position if the data is valid utf8.

Panics

Panics if not called after record was called.

fn expect_byte_fn<F>(&mut self, f: F) -> Result<&mut Self, Option<u8>>

where F: Fn(u8) -> bool,

Returns &mut Self if the function returns true on the next byte. Else returns the byte that was received.

fn expect_byte(&mut self, byte: u8) -> Result<&mut Self, Option<u8>>

Returns &mut Self if the function byte is equal to the next byte. Else returns the actual byte that was received.

fn expect_none(&mut self) -> Result<&mut Self, u8>

Returns &mut Self if the end was reached (next returns None).

fn stop(&mut self) -> Stop<'_, Self>

where Self: Sized,

Returns a ParseIterator that always returns None.

Example

let mut s = StrParser::new("abc");
assert_eq!(b'a', s.next().unwrap());
let mut s = s.stop();
assert!(s.next().is_none());

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'s> ParseIterator<'s> for Parser<'s>

type PointInTime = ParserPointInTime

impl<'s> ParseIterator<'s> for StrParser<'s>

type PointInTime = ParserPointInTime

impl<'s, 'a, T> ParseIterator<'s> for IgnoreByte<'a, T>

where T: ParseIterator<'s>,

type PointInTime = <T as ParseIterator<'s>>::PointInTime

impl<'s, 'a, T> ParseIterator<'s> for RecordIter<'a, T>

where T: ParseIterator<'s>,

type PointInTime = <T as ParseIterator<'s>>::PointInTime

impl<'s, 'a, T> ParseIterator<'s> for SplitOnByteIter<'a, T>

where T: ParseIterator<'s>,

type PointInTime = SplitOnBytePointInTime

impl<'s, 'a, T> ParseIterator<'s> for Stop<'a, T>

where T: ParseIterator<'s>,

type PointInTime = <T as ParseIterator<'s>>::PointInTime

impl<'s, 'a, T, F> ParseIterator<'s> for WhileByteFn<'a, T, F>

where T: ParseIterator<'s>, F: Fn(&u8) -> bool,

type PointInTime = <T as ParseIterator<'s>>::PointInTime