Struct Parser

pub struct Parser<'a, Octs: ?Sized> { /* private fields */ }

A parser for sequentially extracting data from an octets sequence.

The parser wraps an Octets reference and remembers the read position on the referenced sequence. Methods allow reading out data and progressing the position beyond processed data.

Implementations

impl<'a, Octs: ?Sized> Parser<'a, Octs>

pub fn from_ref(octets: &'a Octs) -> Self

where Octs: AsRef<[u8]>,

Creates a new parser atop a reference to an octet sequence.

pub fn with_range<R>(octets: &'a Octs, range: R) -> Self

where Octs: AsRef<[u8]>, R: RangeBounds<usize>,

Creates a new parser only using a range of the given octets.

Panics

Panics if range is decreasing or out of bounds.

pub fn try_with_range<R>(octets: &'a Octs, range: R) -> Option<Self>

where Octs: AsRef<[u8]>, R: RangeBounds<usize>,

Creates a new parser only using a range if possible.

If range is decreasing or out of bounds, returns an Error.

pub fn octets_ref(&self) -> &'a Octs

Returns the wrapped reference to the underlying octets sequence.

pub fn pos(&self) -> usize

Returns the current parse position as an index into the octets.

pub fn len(&self) -> usize

Returns the length of the underlying octet sequence.

This is not the number of octets left for parsing. Use Parser::remaining for that.

pub fn is_empty(&self) -> bool

Returns whether the underlying octets sequence is empty.

This does not return whether there are no more octets left to parse.

impl Parser<'static, [u8]>

pub fn from_static(slice: &'static [u8]) -> Self

Creates a new parser atop a static byte slice.

This function is most useful for testing.

impl<'a, Octs: AsRef<[u8]> + ?Sized> Parser<'a, Octs>

pub fn as_slice(&self) -> &[u8]

Returns an octets slice of the underlying sequence.

The slice covers the entire sequence, not just the remaining data. You can use Parser::peek for that.

pub fn remaining(&self) -> usize

Returns the number of remaining octets to parse.

pub fn peek(&self, len: usize) -> Result<&[u8], ShortInput>

Returns a slice for the next len octets.

If less than len octets are left, returns an error.

pub fn peek_all(&self) -> &[u8]

Returns a slice of the data left to parse.

pub fn seek(&mut self, pos: usize) -> Result<(), ShortInput>

Repositions the parser to the given index.

It is okay to reposition anywhere within the sequence. However, if pos is larger than the length of the sequence, an error is returned.

pub fn advance(&mut self, len: usize) -> Result<(), ShortInput>

Advances the parser‘s position by len octets.

If this would take the parser beyond its end, an error is returned.

pub fn advance_to_end(&mut self)

Advances to the end of the parser.

pub fn check_len(&self, len: usize) -> Result<(), ShortInput>

Checks that there are len octets left to parse.

If there aren’t, returns an error.

impl<'a, Octs: AsRef<[u8]> + ?Sized> Parser<'a, Octs>

pub fn parse_octets( &mut self, len: usize, ) -> Result<Octs::Range<'a>, ShortInput>

where Octs: Octets,

Takes and returns the next len octets.

Advances the parser by len octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_buf(&mut self, buf: &mut [u8]) -> Result<(), ShortInput>

Fills the provided buffer by taking octets from the parser.

Copies as many octets as the buffer is long from the parser into the buffer and advances the parser by that many octets.

If there aren’t enough octets left in the parser to fill the buffer completely, returns an error and leaves the parser untouched.

pub fn parse_parser(&mut self, len: usize) -> Result<Self, ShortInput>

Takes as many octets as requested and returns a parser for them.

If enough octets are remaining, the method clones self, limits its length to the requested number of octets, and returns it. The returned parser will be positioned at wherever self was positioned. The self parser will be advanced by the requested amount of octets.

If there aren’t enough octets left in the parser to fill the buffer completely, returns an error and leaves the parser untouched.

pub fn parse_i8(&mut self) -> Result<i8, ShortInput>

Takes an i8 from the beginning of the parser.

Advances the parser by one octet. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u8(&mut self) -> Result<u8, ShortInput>

Takes a u8 from the beginning of the parser.

Advances the parser by one octet. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

impl<'a, Octs: AsRef<[u8]> + ?Sized> Parser<'a, Octs>

pub fn parse_i16_be(&mut self) -> Result<i16, ShortInput>

Takes a big-endian i16 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by two octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i16_le(&mut self) -> Result<i16, ShortInput>

Takes a little-endian i16 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by two octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u16_be(&mut self) -> Result<u16, ShortInput>

Takes a big-endian u16 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by two octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u16_le(&mut self) -> Result<u16, ShortInput>

Takes a little-endian u16 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by two octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i32_be(&mut self) -> Result<i32, ShortInput>

Takes a big-endian i32 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by four octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i32_le(&mut self) -> Result<i32, ShortInput>

Takes a little-endian i32 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by four octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u32_be(&mut self) -> Result<u32, ShortInput>

Takes a big-endian u32 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by four octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u32_le(&mut self) -> Result<u32, ShortInput>

Takes a little-endian u32 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by four octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i64_be(&mut self) -> Result<i64, ShortInput>

Takes a big-endian i64 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by eight octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i64_le(&mut self) -> Result<i64, ShortInput>

Takes a little-endian i64 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by eight octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u64_be(&mut self) -> Result<u64, ShortInput>

Takes a big-endian u64 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by eight octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u64_le(&mut self) -> Result<u64, ShortInput>

Takes a little-endian u64 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by eight octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i128_be(&mut self) -> Result<i128, ShortInput>

Takes a big-endian i128 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by 16 octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_i128_le(&mut self) -> Result<i128, ShortInput>

Takes a little-endian i128 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by 16 octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u128_be(&mut self) -> Result<u128, ShortInput>

Takes a big-endian u128 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by 16 octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

pub fn parse_u128_le(&mut self) -> Result<u128, ShortInput>

Takes a little-endian u128 from the beginning of the parser.

The value is converted into the system’s own byte order if necessary. The parser is advanced by 16 octets. If there aren’t enough octets left, leaves the parser untouched and returns an error instead.

Trait Implementations

impl<'a, Octs: ?Sized> Clone for Parser<'a, Octs>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, Octs: Debug + ?Sized> Debug for Parser<'a, Octs>

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

Formats the value using the given formatter.

impl<'a, Octs: ?Sized> Copy for Parser<'a, Octs>