Struct BinaryReader

pub struct BinaryReader<'a> {
    pub data: &'a [u8],
}

Reads values from a slice of bytes. The values are encoded using the rules defined by .NET’s System.IO.BinaryWriter.

Most simple fixed-size types are simply encoded using in-memory byte representation of the type, using little-endian memory ordering if applicable.

Variable-length types, such as strings and variable-length integers, have different encodings. Each of the methods that decodes such a type describes its representation.

This type only supports reading values from a slice of bytes. If you need to read values from a file or Read implementation, then you should copy the data into an in-memory buffer first.

Another option is to use “restartable” decoding. Before calling any function that decodes a value, read the data slice (or simply its length). Then, call a function to decode a value (potentially multiple calls to decode multiple values). If any function fails with Err(ReaderError::NeedsMoreData), then go read more data from the source and reset data to point to the original location, plus any new data. Then repeat the calls that decode data.

This is feasible and it may be necessary for some designs. However, simply reading data into Vec<u8> or another in-memory container is likely to be simpler, less bug-prone, and probably faster, too.

Fields

data: &'a [u8]

The input data being parsed. Each time a value is parsed from data, data is reassigned to the remaining data.

Implementations

impl<'a> BinaryReader<'a>

pub fn new(data: &'a [u8]) -> Self

Constructor

pub fn read_u8(&mut self) -> Result<u8, BinaryReaderError>

Reads a single u8 value.

pub fn read_bool(&mut self) -> Result<bool, BinaryReaderError>

Reads a single bool value.

pub fn read_bytes(&mut self, len: usize) -> Result<&'a [u8], BinaryReaderError>

Reads a slice of bytes whose length is len. This function returns a slice reference to the bytes; it does not copy them.

pub fn read_cbytes<const N: usize>( &mut self, ) -> Result<[u8; N], BinaryReaderError>

Reads a small array of bytes, with a constant length.

pub fn read_cbytes_ref<const N: usize>( &mut self, ) -> Result<&[u8; N], BinaryReaderError>

Reads a small array of bytes, with a constant length.

pub fn read_u16(&mut self) -> Result<u16, BinaryReaderError>

Reads a u16 in little-endian byte order.

pub fn read_u32(&mut self) -> Result<u32, BinaryReaderError>

Reads a u32 in little-endian byte order.

pub fn read_u64(&mut self) -> Result<u64, BinaryReaderError>

Reads a u64 in little-endian byte order.

pub fn read_i16(&mut self) -> Result<i16, BinaryReaderError>

Reads a i16 in little-endian byte order.

pub fn read_i32(&mut self) -> Result<i32, BinaryReaderError>

Reads a i32 in little-endian byte order.

pub fn read_i64(&mut self) -> Result<i64, BinaryReaderError>

Reads a i64 in little-endian byte order.

pub fn read_7bit_encoded_i32(&mut self) -> Result<i32, BinaryReaderError>

Reads a variable-length integer and returns the value in i32.

pub fn read_7bit_encoded_i64(&mut self) -> Result<i64, BinaryReaderError>

Reads a variable-length integer and returns the value in i64.

pub fn read_utf8_bytes(&mut self) -> Result<&'a [u8], BinaryReaderError>

Reads a length-prefixed UTF-8 string.

This does not copy any data. It reads the prefixed length, locates the contents of the string, then returns the string data as a &[u8].

The caller must handle validating that the string is well-formed UTF-8, if necessary.

pub fn read_utf8_bstr(&mut self) -> Result<&'a BStr, BinaryReaderError>

Reads a length-prefixed UTF-8 string.

This does not copy any data. It reads the prefixed length, locates the contents of the string, then returns the string data as a bstr::BStr.

The caller must handle validating that the string is well-formed UTF-8, if necessary.

The encoded stream does not contain any information that distinguishes UTF-8 strings and UTF-16 strings, so applications will need to make sure that they call the correct read_utf8_* or read_utf16_* function.

pub fn read_utf8_str(&mut self) -> Result<&'a str, BinaryReaderError>

Reads a length-prefixed UTF-8 string and returns it as &str.

This does not copy any data. It reads the prefixed length, locates the contents of the string, validates that the contents are well-formed UTF-8 and returns the string slice.

The encoded stream does not contain any information that distinguishes UTF-8 strings and UTF-16 strings, so applications will need to make sure that they call the correct read_utf8_* or read_utf16_* function.

pub fn read_utf8_string_lossy( &mut self, ) -> Result<Cow<'a, str>, BinaryReaderError>

Reads a length-prefixed UTF-8 string and returns it as Cow<str>.

The input string is expected to be valid UTF-8. However, if the input contains byte sequences that do not code for valid UTF-8, then those sequences will be replaced with the Unicore replacement character and the rest of the string will be processed.

The encoded stream does not contain any information that distinguishes UTF-8 strings and UTF-16 strings, so applications will need to make sure that they call the correct read_utf8_* or read_utf16_* function.

pub fn read_utf16_wchars(&mut self) -> Result<&'a [U16<LE>], BinaryReaderError>

Reads a length-prefixed UTF-16 string and returns it as &[U16<LE>].

This does not copy any data. It reads the prefixed length, locates the contents of the string, validates that the contents are the right size for UTF-16 (meaning: the length in bytes is a multiple of 2) and returns the string slice.

The caller is responsible for converting the returned slice to a different, more usable form.

pub fn read_utf16_string(&mut self) -> Result<String, BinaryReaderError>

Reads a length-prefixed UTF-16 string and returns it as String.

The input string is required to be well-formed UTF-16; if it contains illegal UTF-16 code points or illegal surrogate sequences, then this function will return Err(ReaderError::Invalid).

The length in bytes of the string is required to be a multiple of 2. If it is not, then this function will return Err(ReaderError::Invalid).

The encoded stream does not contain any information that distinguishes UTF-8 strings and UTF-16 strings, so applications will need to make sure that they call the correct read_utf8_* or read_utf16_* function.

pub fn read_utf16_string_lossy(&mut self) -> Result<String, BinaryReaderError>

Reads a length-prefixed UTF-16 string and returns it as String.

If the input sequence contains illegal UTF-16 code points or illegal surrogate sequences, then this function will replace the illegal code units with the Unicode replacement character.

The length in bytes of the string is required to be a multiple of 2. If it is not, then this function will return Err(ReaderError::Invalid).