Struct bytes_parser::BytesParser

pub struct BytesParser<'a> { /* private fields */ }

A zero-copy bytes parser, useful when parsing bespoke binary protocols.

It wraps a reference to a byte-array, and adds a thin parsing layer: calls to the parse_* reads the bytes and updates an internal cursor sequentially. This makes for a very linear sequence of calls, when in need to consume, for example, messages for a bespoke binary protocol.

By default, the parsing is done using the ParsingEndian::BE endian system, but that can be configured.

The internal cursor progresses sequentially from position 0 (i.e. no bytes has been parsed yet) to maximum position of BytesParser::length (i.e. all bytes have been parsed).

If necessary, methods are provided to move the cursor around, with error checking in case the cursor is moved outside the boundaries of the underlying array.

Implementations

impl<'a> BytesParser<'a>

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

Parse ai8 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a i8.

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

Parse au8 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a u8.

pub fn parse_i16(&mut self) -> Result<i16, BytesParserError>

Parse ai16 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a i16.

pub fn parse_u16(&mut self) -> Result<u16, BytesParserError>

Parse au16 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a u16.

pub fn parse_i32(&mut self) -> Result<i32, BytesParserError>

Parse ai32 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a i32.

pub fn parse_u32(&mut self) -> Result<u32, BytesParserError>

Parse au32 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a u32.

pub fn parse_i64(&mut self) -> Result<i64, BytesParserError>

Parse ai64 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a i64.

pub fn parse_u64(&mut self) -> Result<u64, BytesParserError>

Parse au64 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a u64.

pub fn parse_i128(&mut self) -> Result<i128, BytesParserError>

Parse ai128 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a i128.

pub fn parse_u128(&mut self) -> Result<u128, BytesParserError>

Parse au128 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a u128.

pub fn parse_f32(&mut self) -> Result<f32, BytesParserError>

Parse af32 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a f32.

pub fn parse_f64(&mut self) -> Result<f64, BytesParserError>

Parse af64 and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a f64.

pub fn parse_isize(&mut self) -> Result<isize, BytesParserError>

Parse aisize and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a isize.

pub fn parse_usize(&mut self) -> Result<usize, BytesParserError>

Parse ausize and update the internal cursor accordingly.

It produces an error if BytesParser::parseable returns an amount inferior to the amount of bytes occupied by a usize.

pub fn parse_str_utf8(&mut self, size: usize) -> Result<&str, BytesParserError>

Parse a &str and update the internal cursor accordingly.

It produces an error if BytesParser::parseable() returns an amount inferior to the given size.

Typically for binary protocols, the string is preceded by an integer representation of the size of the string in bytes. Unfortunately there is no single standard for how that integer is encoded (16 bits? 32 bits?), hence the required argument size.

The data returned is a “view” of the original bytes array, so that should be considered when handling the returned reference and its lifetime. If the returned reference has to outlast the inner bytes array, it should probably be cloned or turned into a String.

Arguments

• size - Size of the UTF-8 &str to parse, in bytes. For Arabic characters, this will be equivalent to the string length, as UTF-8 uses 1 byte per scalar value. But for non-Arabic characters, UTF-8 might requires multiple bytes per scalar value. More details can be found in the Rust Programming Language book. Because of this, determining how many bytes to consume to parse the String is left to the user.

pub fn parse_char_u32(&mut self) -> Result<char, BytesParserError>

Parse a single char from a u32 (i.e. 4 bytes).s

As per char representation, Rust uses the fixed amount of 4 bytes to encode a single character.

pub fn parse_slice(&mut self, size: usize) -> Result<&[u8], BytesParserError>

“Parse” a slice of bytes &[u8] of given size, starting from Self::position.

This doesn’t actually create anything: it cuts a slice from the inner bytes array, that the user can then manipulate in other ways.

The data returned is a “view” of the original bytes array, so that should be considered when handling the returned reference and its lifetime. If the returned slice has to outlast the inner bytes array, it should probably be cloned.

Arguments

• size - The size of the new slice to cut. The slice will be cut starting from the current position of the internal cursor (i.e. Self::position).

pub fn from_slice(
    &mut self,
    size: usize
) -> Result<BytesParser<'_>, BytesParserError>

Creates a new BytesParser that is set to use a slice of bytes as its inner byte array.

This uses Self::parse_slice to cut a &[u8], and then initializes a new BytesParser using Self::from.

Arguments

• size - The size of the new slice to cut and wrap inside a BytesParser.

pub const fn length(&self) -> usize

Length of the internal bytes array.

pub const fn is_empty(&self) -> bool

Returns true if the internal bytes array is empty.

pub const fn position(&self) -> usize

Returns the 0-based position of the cursor.

The index returned corresponds to the next bytes that would be parsed.

pub const fn is_at_start(&self) -> bool

Returns true if the internal cursor points at the very start of the bytes array.

When first created, this will return true.

pub const fn is_at_end(&self) -> bool

Returns true if the internal cursor points at the very end of the bytes array.

When all bytes have been parsed, this will return true.

pub const fn parseable(&self) -> usize

Returns the amount of bytes that can still be parsed.

If BytesParser::is_at_start returns true, then this will return the same as BytesParser::length. If BytesParser::is_at_end returns true, then this will return 0.

pub fn reset(&mut self)

Reset cursor to the very start of the bytes array.

This can be used to re-parse bytes.

After this is called, BytesParser::is_at_start will return true

pub fn move_forward(&mut self, amount: usize) -> Result<(), BytesParserError>

Move internal cursor forward by amount.

The new cursor position corresponds to the next byte that would be parsed. It produces an error if the new cursor position would fall out-of-bound of the internal bytes array.

Arguments

• amount - Amount of bytes to move forward the cursor.

pub fn move_backward(&mut self, amount: usize) -> Result<(), BytesParserError>

Move internal cursor backward by amount.

The new cursor position corresponds to the next byte that would be parsed. It produces an error if the new cursor position would fall out-of-bound of the internal bytes array.

Arguments

• amount - Amount of bytes to move backward the cursor.

pub fn move_at(&mut self, position: usize) -> Result<(), BytesParserError>

Move internal cursor at position.

The new cursor position corresponds to the next byte that would be parsed. It produces an error if the new cursor position would fall out-of-bound of the internal bytes array.

Arguments

• position - Where to move the cursor at.

pub fn set_endian(&mut self, endian: ParsingEndian)

Sets the ParsingEndian to be used when parsing scalar types from the internal bytes array.

Arguments

• endian - The ParsingEndian to use when calling BytesParser::parse_<scalar_type>.

pub const fn endian(&self) -> ParsingEndian

Return the ParsingEndian currently used.

Trait Implementations

impl<'a> Clone for BytesParser<'a>

fn clone(&self) -> BytesParser<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for BytesParser<'a>

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

Formats the value using the given formatter.

impl<'a> From<&'a [u8]> for BytesParser<'a>

fn from(bytes: &'a [u8]) -> Self

Converts to this type from the input type.

impl<'a> Copy for BytesParser<'a>