Struct bitreader::BitReader

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

BitReader reads data from a byte slice at the granularity of a single bit.

Implementations

impl<'a> BitReader<'a>

pub fn new(bytes: &'a [u8]) -> BitReader<'a>

Construct a new BitReader from a byte slice. The returned reader lives at most as long as the slice given to is valid.

pub fn relative_reader(&self) -> BitReader<'a>

Returns a copy of current BitReader, with the difference that its position() returns positions relative to the position of the original BitReader at the construction time. After construction, both readers are otherwise completely independent, except of course for sharing the same source data.

use bitreader::BitReader;

let bytes = &[0b11110000, 0b00001111];
let mut original = BitReader::new(bytes);
assert_eq!(original.read_u8(4).unwrap(), 0b1111);
assert_eq!(original.position(), 4);

let mut relative = original.relative_reader();
assert_eq!(relative.position(), 0);

assert_eq!(original.read_u8(8).unwrap(), 0);
assert_eq!(relative.read_u8(8).unwrap(), 0);

assert_eq!(original.position(), 12);
assert_eq!(relative.position(), 8);

pub fn relative_reader_atmost(&self, len: u64) -> BitReader<'a>

Returns a copy of current BitReader, with the difference that its position() returns positions relative to the position of the original BitReader at the construction time, and will not allow reading more than len bits. After construction, both readers are otherwise

use bitreader::BitReader;
use bitreader::BitReaderError;

let bytes = &[0b11110000, 0b00001111];
let mut original = BitReader::new(bytes);
assert_eq!(original.read_u8(4).unwrap(), 0b1111);
assert_eq!(original.position(), 4);

let mut relative = original.relative_reader_atmost(8);
assert_eq!(relative.position(), 0);

assert_eq!(original.read_u8(8).unwrap(), 0);
assert_eq!(relative.read_u8(8).unwrap(), 0);

assert_eq!(original.position(), 12);
assert_eq!(relative.position(), 8);

assert_eq!(relative.read_u8(8).unwrap_err(), BitReaderError::NotEnoughData{
   position: 8,
   length: 8,
   requested: 8
});

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

Read at most 8 bits into a u8.

pub fn peek_u8(&self, bit_count: u8) -> Result<u8>

Read at most 8 bits into a u8, but without moving the cursor forward.

pub fn read_u8_slice(&mut self, output_bytes: &mut [u8]) -> Result<()>

Fills the entire output_bytes slice. If there aren’t enough bits remaining after the internal cursor’s current position, the cursor won’t be moved forward and the contents of output_bytes won’t be modified.

pub fn read_u16(&mut self, bit_count: u8) -> Result<u16>

Read at most 16 bits into a u16.

pub fn peek_u16(&self, bit_count: u8) -> Result<u16>

Read at most 16 bits into a u16, but without moving the cursor forward.

pub fn read_u32(&mut self, bit_count: u8) -> Result<u32>

Read at most 32 bits into a u32.

pub fn peek_u32(&self, bit_count: u8) -> Result<u32>

Read at most 32 bits into a u32, but without moving the cursor forward.

pub fn read_u64(&mut self, bit_count: u8) -> Result<u64>

Read at most 64 bits into a u64.

pub fn peek_u64(&self, bit_count: u8) -> Result<u64>

Read at most 64 bits into a u64, but without moving the cursor forward.

pub fn read_i8(&mut self, bit_count: u8) -> Result<i8>

Read at most 8 bits into a i8. Assumes the bits are stored in two’s complement format.

pub fn read_i16(&mut self, bit_count: u8) -> Result<i16>

Read at most 16 bits into a i16. Assumes the bits are stored in two’s complement format.

pub fn read_i32(&mut self, bit_count: u8) -> Result<i32>

Read at most 32 bits into a i32. Assumes the bits are stored in two’s complement format.

pub fn read_i64(&mut self, bit_count: u8) -> Result<i64>

Read at most 64 bits into a i64. Assumes the bits are stored in two’s complement format.

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

Read a single bit as a boolean value. Interprets 1 as true and 0 as false.

pub fn peek_bool(&self) -> Result<bool>

Read a single bit as a boolean value, but without moving the cursor forward. Interprets 1 as true and 0 as false.

pub fn skip(&mut self, bit_count: u64) -> Result<()>

Skip arbitrary number of bits. However, you can skip at most to the end of the byte slice.

pub fn position(&self) -> u64

Returns the position of the cursor, or how many bits have been read so far.

pub fn remaining(&self) -> u64

Returns the number of bits not yet read from the underlying slice.

pub fn is_aligned(&self, alignment_bytes: u32) -> bool

Helper to make sure the “bit cursor” is exactly at the beginning of a byte, or at specific multi-byte alignment position.

For example reader.is_aligned(1) returns true if exactly n bytes, or n * 8 bits, has been read. Similarly, reader.is_aligned(4) returns true if exactly n * 32 bits, or n 4-byte sequences has been read.

This function can be used to validate the data is being read properly, for example by adding invocations wrapped into debug_assert!() to places where it is known the data should be n-byte aligned.

pub fn align(&mut self, alignment_bytes: u32) -> Result<()>

Helper to move the “bit cursor” to exactly the beginning of a byte, or to a specific multi-byte alignment position.

That is, reader.align(n) moves the cursor to the next position that is a multiple of n * 8 bits, if it’s not correctly aligned already.