Trait BinReader

pub trait BinReader<'r>
where
    Self: Sized + AsRef<[u8]> + Borrow<[u8]> + Read + BufRead,
{
    // Required methods
    fn from_slice_with_offset(
        slice: &'r [u8],
        initial_offset: usize,
        endidness: Endidness,
    ) -> Result<Self>;
    fn size(&self) -> usize;
    fn initial_offset(&self) -> usize;
    fn current_offset(&self) -> usize;
    fn endidness(&self) -> Endidness;
    fn change_endidness(&mut self, endidness: Endidness);
    fn advance_to(&self, offset: usize) -> Result<()>;
    fn advance_by(&self, num_bytes: isize) -> Result<()>;

    // Provided methods
    fn from_slice(slice: &'r [u8], endidness: Endidness) -> Result<Self> { ... }
    fn next_n_bytes(&self, num_bytes: usize) -> Result<Bytes> { ... }
    fn lower_offset_limit(&self) -> usize { ... }
    fn upper_offset_limit(&self) -> usize { ... }
    fn is_empty(&self) -> bool { ... }
    fn remaining(&self) -> usize { ... }
    fn validate_offset(&self, offset: usize, size: usize) -> Result<()> { ... }
    fn relative_offset(&self, abs_offset: usize) -> Result<usize> { ... }
    fn next_bytes_are(&self, prefix: &[u8]) -> Result<bool> { ... }
    fn bytes_at(&self, offset: usize, buf: &mut [u8]) -> Result<()> { ... }
    fn subseq(&self, offset: usize, num_bytes: usize) -> Result<&[u8]> { ... }
    fn range(&self, start: usize, end: usize) -> Result<&[u8]> { ... }
    fn next_bytes(&self, buf: &mut [u8]) -> Result<()> { ... }
    fn current_u8(&self) -> Result<u8> { ... }
    fn current_i8_ne(&self) -> Result<i8> { ... }
    fn current_u16_be(&self) -> Result<u16> { ... }
    fn current_u16_le(&self) -> Result<u16> { ... }
    fn current_i16_be(&self) -> Result<i16> { ... }
    fn current_i16_le(&self) -> Result<i16> { ... }
    fn current_u32_be(&self) -> Result<u32> { ... }
    fn current_u32_le(&self) -> Result<u32> { ... }
    fn current_i32_be(&self) -> Result<i32> { ... }
    fn current_i32_le(&self) -> Result<i32> { ... }
    fn current_u64_be(&self) -> Result<u64> { ... }
    fn current_u64_le(&self) -> Result<u64> { ... }
    fn current_i64_be(&self) -> Result<i64> { ... }
    fn current_i64_le(&self) -> Result<i64> { ... }
    fn current_u128_be(&self) -> Result<u128> { ... }
    fn current_u128_le(&self) -> Result<u128> { ... }
    fn current_i128_be(&self) -> Result<i128> { ... }
    fn current_i128_le(&self) -> Result<i128> { ... }
    fn u8_at(&self, offset: usize) -> Result<u8> { ... }
    fn i8_ne_at(&self, offset: usize) -> Result<i8> { ... }
    fn u16_be_at(&self, offset: usize) -> Result<u16> { ... }
    fn u16_le_at(&self, offset: usize) -> Result<u16> { ... }
    fn i16_be_at(&self, offset: usize) -> Result<i16> { ... }
    fn i16_le_at(&self, offset: usize) -> Result<i16> { ... }
    fn u32_be_at(&self, offset: usize) -> Result<u32> { ... }
    fn u32_le_at(&self, offset: usize) -> Result<u32> { ... }
    fn i32_be_at(&self, offset: usize) -> Result<i32> { ... }
    fn i32_le_at(&self, offset: usize) -> Result<i32> { ... }
    fn u64_be_at(&self, offset: usize) -> Result<u64> { ... }
    fn u64_le_at(&self, offset: usize) -> Result<u64> { ... }
    fn i64_be_at(&self, offset: usize) -> Result<i64> { ... }
    fn i64_le_at(&self, offset: usize) -> Result<i64> { ... }
    fn u128_be_at(&self, offset: usize) -> Result<u128> { ... }
    fn u128_le_at(&self, offset: usize) -> Result<u128> { ... }
    fn i128_be_at(&self, offset: usize) -> Result<i128> { ... }
    fn i128_le_at(&self, offset: usize) -> Result<i128> { ... }
    fn u16_at(&self, offset: usize) -> Result<u16> { ... }
    fn u32_at(&self, offset: usize) -> Result<u32> { ... }
    fn u64_at(&self, offset: usize) -> Result<u64> { ... }
    fn u128_at(&self, offset: usize) -> Result<u128> { ... }
    fn i16_at(&self, offset: usize) -> Result<i16> { ... }
    fn i32_at(&self, offset: usize) -> Result<i32> { ... }
    fn i64_at(&self, offset: usize) -> Result<i64> { ... }
    fn i128_at(&self, offset: usize) -> Result<i128> { ... }
    fn next_u8(&self) -> Result<u8> { ... }
    fn next_i8_ne(&self) -> Result<i8> { ... }
    fn next_u16_be(&self) -> Result<u16> { ... }
    fn next_u16_le(&self) -> Result<u16> { ... }
    fn next_i16_be(&self) -> Result<i16> { ... }
    fn next_i16_le(&self) -> Result<i16> { ... }
    fn next_u32_be(&self) -> Result<u32> { ... }
    fn next_u32_le(&self) -> Result<u32> { ... }
    fn next_i32_be(&self) -> Result<i32> { ... }
    fn next_i32_le(&self) -> Result<i32> { ... }
    fn next_u64_be(&self) -> Result<u64> { ... }
    fn next_u64_le(&self) -> Result<u64> { ... }
    fn next_i64_be(&self) -> Result<i64> { ... }
    fn next_i64_le(&self) -> Result<i64> { ... }
    fn next_u128_be(&self) -> Result<u128> { ... }
    fn next_u128_le(&self) -> Result<u128> { ... }
    fn next_i128_be(&self) -> Result<i128> { ... }
    fn next_i128_le(&self) -> Result<i128> { ... }
    fn next_u16(&self) -> Result<u16> { ... }
    fn next_u32(&self) -> Result<u32> { ... }
    fn next_u64(&self) -> Result<u64> { ... }
    fn next_u128(&self) -> Result<u128> { ... }
    fn next_i8(&self) -> Result<i8> { ... }
    fn next_i16(&self) -> Result<i16> { ... }
    fn next_i32(&self) -> Result<i32> { ... }
    fn next_i64(&self) -> Result<i64> { ... }
    fn next_i128(&self) -> Result<i128> { ... }
}

The primary trait of this crate; a BinReader is designed to be a common interface between your program and binary data.

While not required, most BinReaders should implement the std::io::Read, std::io::Seek, std::io::BufRead, and std::borrow::Borrow<&[u8]> traits.

Additionally, there are two sub-traits of BinReader:

• OwnableBinReader which owns the data contained within it.
• SliceableBinReader which allows you to easily create SliceRefBinReaders from another reader.

Offsets

Instead of indexes, BinReaders use offsets. Now, in most cases these are probably going to be the same. However, you can specify an initial offset that will essentially change the index of zero to whatever the initial_offset is. For example:

let test_data = [0x00, 0x01, 0x02, 0x03, 0x04, 0x05];
let reader = RandomAccessBinReader::from_slice_with_offset(&test_data, 100, Endidness::Big);
assert_eq!(reader.u8_at(100).unwrap(), 0);

Validation

One thing you may have noticed is that we had to unwrap the value. Most of a BinReader’s methods first check to make sure the provided offset is valid. For example:

assert!(matches!(reader.u8_at(99), Err(Error::OffsetTooSmall(99))));

Limits

The lower and upper limits of valid offsets can be retrieved via the BinReader::lower_offset_limit and BinReader::upper_offset_limit methods respectively.

An important note: the BinReader::size method returns how much data is in the reader, not what the highest valid offset is.

Required Methods

fn from_slice_with_offset( slice: &'r [u8], initial_offset: usize, endidness: Endidness, ) -> Result<Self>

Generates a new BinReader using the provided slice, initial offset, and endidness. While the exact implementation of this varies from implementation to implementation, OwnableBinReaders will, more than likely, copy the data in the slice.

fn size(&self) -> usize

The amount of data in the reader. If the reader’s size changes (which none of the implementations currently do), then this should return how much data was initially in the reader.

fn initial_offset(&self) -> usize

The initial offset of the BinReader. For more information, see the Offsets section of the BinReader documentation.

fn current_offset(&self) -> usize

The current offset of the reader’s cursor.

fn endidness(&self) -> Endidness

The endidness of the reader.

fn change_endidness(&mut self, endidness: Endidness)

Changes the default endidness.

fn advance_to(&self, offset: usize) -> Result<()>

Sets the reader’s BinReader::current_offset.

fn advance_by(&self, num_bytes: isize) -> Result<()>

Alters the BinReader::current_offset by the given amount.

Provided Methods

fn from_slice(slice: &'r [u8], endidness: Endidness) -> Result<Self>

Functions the same as the BinReader::from_slice_with_offset, except the initial offset is always 0.

fn next_n_bytes(&self, num_bytes: usize) -> Result<Bytes>

Returns a Bytes object of the requested size containing the next n bytes (where n is the num_bytes parameter) and then advances the cursor by that much.

fn lower_offset_limit(&self) -> usize

The lowest valid offset that can be requested. By default, this is the same as BinReader::initial_offset.

fn upper_offset_limit(&self) -> usize

The highest valid offset that can be requested. By default, this is the reader’s BinReader::size plus its BinReader::initial_offset.

fn is_empty(&self) -> bool

Checks whether or not there is any data left, based off of the BinReader::current_offset.

fn remaining(&self) -> usize

The amount of data left, based off of the BinReader::current_offset.

fn validate_offset(&self, offset: usize, size: usize) -> Result<()>

A helper method that validates an offset (mostly used by reader implementations).

If the offset is valid, then Ok(()) will be returned. Otherwise, the appropriate Error is returned (wrapped in Err, of course).

fn relative_offset(&self, abs_offset: usize) -> Result<usize>

Takes an absolute offset and converts it to a relative offset, based off of the BinReader::current_offset.

fn next_bytes_are(&self, prefix: &[u8]) -> Result<bool>

Returns true if the next bytes are the same as the ones provided.

fn bytes_at(&self, offset: usize, buf: &mut [u8]) -> Result<()>

Fills the provided buffer with bytes, starting at the provided offset. This does not alter the BinReader::current_offset.

fn subseq(&self, offset: usize, num_bytes: usize) -> Result<&[u8]>

Returns a subsequence (i.e. a &[u8]) of data of the requested size beginning at the provided offset.

fn range(&self, start: usize, end: usize) -> Result<&[u8]>

Returns a slice of the data between the provided starting and ending offsets.

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

Fills the provided buffer with the next n bytes, where n is the length of the buffer. This then advances the BinReader::current_offset by n.

fn current_u8(&self) -> Result<u8>

Gets the u8 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i8_ne(&self) -> Result<i8>

Gets the nelong endian i8 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u16_be(&self) -> Result<u16>

Gets the belong endian u16 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u16_le(&self) -> Result<u16>

Gets the lelong endian u16 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i16_be(&self) -> Result<i16>

Gets the belong endian i16 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i16_le(&self) -> Result<i16>

Gets the lelong endian i16 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u32_be(&self) -> Result<u32>

Gets the belong endian u32 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u32_le(&self) -> Result<u32>

Gets the lelong endian u32 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i32_be(&self) -> Result<i32>

Gets the belong endian i32 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i32_le(&self) -> Result<i32>

Gets the lelong endian i32 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u64_be(&self) -> Result<u64>

Gets the belong endian u64 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u64_le(&self) -> Result<u64>

Gets the lelong endian u64 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i64_be(&self) -> Result<i64>

Gets the belong endian i64 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i64_le(&self) -> Result<i64>

Gets the lelong endian i64 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u128_be(&self) -> Result<u128>

Gets the belong endian u128 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_u128_le(&self) -> Result<u128>

Gets the lelong endian u128 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i128_be(&self) -> Result<i128>

Gets the belong endian i128 at the BinReader::current_offset without altering the BinReader::current_offset.

fn current_i128_le(&self) -> Result<i128>

Gets the lelong endian i128 at the BinReader::current_offset without altering the BinReader::current_offset.

fn u8_at(&self, offset: usize) -> Result<u8>

Gets the u8 at the provided offset without altering the BinReader::current_offset.

fn i8_ne_at(&self, offset: usize) -> Result<i8>

Gets the nelong endian i8 at the provided offset without altering the BinReader::current_offset.

fn u16_be_at(&self, offset: usize) -> Result<u16>

Gets the belong endian u16 at the provided offset without altering the BinReader::current_offset.

fn u16_le_at(&self, offset: usize) -> Result<u16>

Gets the lelong endian u16 at the provided offset without altering the BinReader::current_offset.

fn i16_be_at(&self, offset: usize) -> Result<i16>

Gets the belong endian i16 at the provided offset without altering the BinReader::current_offset.

fn i16_le_at(&self, offset: usize) -> Result<i16>

Gets the lelong endian i16 at the provided offset without altering the BinReader::current_offset.

fn u32_be_at(&self, offset: usize) -> Result<u32>

Gets the belong endian u32 at the provided offset without altering the BinReader::current_offset.

fn u32_le_at(&self, offset: usize) -> Result<u32>

Gets the lelong endian u32 at the provided offset without altering the BinReader::current_offset.

fn i32_be_at(&self, offset: usize) -> Result<i32>

Gets the belong endian i32 at the provided offset without altering the BinReader::current_offset.

fn i32_le_at(&self, offset: usize) -> Result<i32>

Gets the lelong endian i32 at the provided offset without altering the BinReader::current_offset.

fn u64_be_at(&self, offset: usize) -> Result<u64>

Gets the belong endian u64 at the provided offset without altering the BinReader::current_offset.

fn u64_le_at(&self, offset: usize) -> Result<u64>

Gets the lelong endian u64 at the provided offset without altering the BinReader::current_offset.

fn i64_be_at(&self, offset: usize) -> Result<i64>

Gets the belong endian i64 at the provided offset without altering the BinReader::current_offset.

fn i64_le_at(&self, offset: usize) -> Result<i64>

Gets the lelong endian i64 at the provided offset without altering the BinReader::current_offset.

fn u128_be_at(&self, offset: usize) -> Result<u128>

Gets the belong endian u128 at the provided offset without altering the BinReader::current_offset.

fn u128_le_at(&self, offset: usize) -> Result<u128>

Gets the lelong endian u128 at the provided offset without altering the BinReader::current_offset.

fn i128_be_at(&self, offset: usize) -> Result<i128>

Gets the belong endian i128 at the provided offset without altering the BinReader::current_offset.

fn i128_le_at(&self, offset: usize) -> Result<i128>

Gets the lelong endian i128 at the provided offset without altering the BinReader::current_offset.

fn u16_at(&self, offset: usize) -> Result<u16>

Gets the u16 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn u32_at(&self, offset: usize) -> Result<u32>

Gets the u32 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn u64_at(&self, offset: usize) -> Result<u64>

Gets the u64 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn u128_at(&self, offset: usize) -> Result<u128>

Gets the u128 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn i16_at(&self, offset: usize) -> Result<i16>

Gets the i16 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn i32_at(&self, offset: usize) -> Result<i32>

Gets the i32 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn i64_at(&self, offset: usize) -> Result<i64>

Gets the i64 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn i128_at(&self, offset: usize) -> Result<i128>

Gets the i128 using the default endidness at the provided offset without altering the BinReader::current_offset. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_u8(&self) -> Result<u8>

Gets the current byte and then advances the cursor.

fn next_i8_ne(&self) -> Result<i8>

Gets the nelong endian i8 at the BinReader::current_offset and then advances it by 1.

fn next_u16_be(&self) -> Result<u16>

Gets the belong endian u16 at the BinReader::current_offset and then advances it by 1.

fn next_u16_le(&self) -> Result<u16>

Gets the lelong endian u16 at the BinReader::current_offset and then advances it by 1.

fn next_i16_be(&self) -> Result<i16>

Gets the belong endian i16 at the BinReader::current_offset and then advances it by 1.

fn next_i16_le(&self) -> Result<i16>

Gets the lelong endian i16 at the BinReader::current_offset and then advances it by 1.

fn next_u32_be(&self) -> Result<u32>

Gets the belong endian u32 at the BinReader::current_offset and then advances it by 1.

fn next_u32_le(&self) -> Result<u32>

Gets the lelong endian u32 at the BinReader::current_offset and then advances it by 1.

fn next_i32_be(&self) -> Result<i32>

Gets the belong endian i32 at the BinReader::current_offset and then advances it by 1.

fn next_i32_le(&self) -> Result<i32>

Gets the lelong endian i32 at the BinReader::current_offset and then advances it by 1.

fn next_u64_be(&self) -> Result<u64>

Gets the belong endian u64 at the BinReader::current_offset and then advances it by 1.

fn next_u64_le(&self) -> Result<u64>

Gets the lelong endian u64 at the BinReader::current_offset and then advances it by 1.

fn next_i64_be(&self) -> Result<i64>

Gets the belong endian i64 at the BinReader::current_offset and then advances it by 1.

fn next_i64_le(&self) -> Result<i64>

Gets the lelong endian i64 at the BinReader::current_offset and then advances it by 1.

fn next_u128_be(&self) -> Result<u128>

Gets the belong endian u128 at the BinReader::current_offset and then advances it by 1.

fn next_u128_le(&self) -> Result<u128>

Gets the lelong endian u128 at the BinReader::current_offset and then advances it by 1.

fn next_i128_be(&self) -> Result<i128>

Gets the belong endian i128 at the BinReader::current_offset and then advances it by 1.

fn next_i128_le(&self) -> Result<i128>

Gets the lelong endian i128 at the BinReader::current_offset and then advances it by 1.

fn next_u16(&self) -> Result<u16>

Gets the u16 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_u32(&self) -> Result<u32>

Gets the u16 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_u64(&self) -> Result<u64>

Gets the u16 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_u128(&self) -> Result<u128>

Gets the u16 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_i8(&self) -> Result<i8>

Gets the i8 at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_i16(&self) -> Result<i16>

Gets the i16 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_i32(&self) -> Result<i32>

Gets the i32 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_i64(&self) -> Result<i64>

Gets the i64 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

fn next_i128(&self) -> Result<i128>

Gets the i128 using the default endidness at the BinReader::current_offset and then advances it by 1. If the current endidness is Endidness::Unknown, then an error is returned.

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<'r> BinReader<'r> for RandomAccessBinReader

impl<'r, 'o> BinReader<'o> for SliceRefBinReader<'r>

where 'o: 'r,