Struct bytes_parser::BytesParser
source · pub struct BytesParser<'a> { /* private fields */ }
Expand description
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§
source§impl<'a> BytesParser<'a>
impl<'a> BytesParser<'a>
sourcepub fn parse_i8(&mut self) -> Result<i8, BytesParserError>
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
.
sourcepub fn parse_u8(&mut self) -> Result<u8, BytesParserError>
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
.
sourcepub fn parse_i16(&mut self) -> Result<i16, BytesParserError>
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
.
sourcepub fn parse_u16(&mut self) -> Result<u16, BytesParserError>
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
.
sourcepub fn parse_i32(&mut self) -> Result<i32, BytesParserError>
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
.
sourcepub fn parse_u32(&mut self) -> Result<u32, BytesParserError>
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
.
sourcepub fn parse_i64(&mut self) -> Result<i64, BytesParserError>
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
.
sourcepub fn parse_u64(&mut self) -> Result<u64, BytesParserError>
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
.
sourcepub fn parse_i128(&mut self) -> Result<i128, BytesParserError>
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
.
sourcepub fn parse_u128(&mut self) -> Result<u128, BytesParserError>
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
.
sourcepub fn parse_f32(&mut self) -> Result<f32, BytesParserError>
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
.
sourcepub fn parse_f64(&mut self) -> Result<f64, BytesParserError>
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
.
sourcepub fn parse_isize(&mut self) -> Result<isize, BytesParserError>
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
.
sourcepub fn parse_usize(&mut self) -> Result<usize, BytesParserError>
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
.
sourcepub fn parse_str_utf8(&mut self, size: usize) -> Result<&str, BytesParserError>
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 theString
is left to the user.
sourcepub fn parse_char_u32(&mut self) -> Result<char, BytesParserError>
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.
sourcepub fn parse_slice(&mut self, size: usize) -> Result<&[u8], BytesParserError>
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
).
sourcepub fn from_slice(
&mut self,
size: usize
) -> Result<BytesParser<'_>, BytesParserError>
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 aBytesParser
.
sourcepub const fn position(&self) -> usize
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.
sourcepub const fn is_at_start(&self) -> bool
pub const fn is_at_start(&self) -> bool
sourcepub const fn parseable(&self) -> usize
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
.
sourcepub fn reset(&mut self)
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
sourcepub fn move_forward(&mut self, amount: usize) -> Result<(), BytesParserError>
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.
sourcepub fn move_backward(&mut self, amount: usize) -> Result<(), BytesParserError>
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.
sourcepub fn move_at(&mut self, position: usize) -> Result<(), BytesParserError>
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.
sourcepub fn set_endian(&mut self, endian: ParsingEndian)
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 callingBytesParser::parse_<scalar_type>
.
sourcepub const fn endian(&self) -> ParsingEndian
pub const fn endian(&self) -> ParsingEndian
Return the ParsingEndian currently used.
Trait Implementations§
source§impl<'a> Clone for BytesParser<'a>
impl<'a> Clone for BytesParser<'a>
source§fn clone(&self) -> BytesParser<'a>
fn clone(&self) -> BytesParser<'a>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more