Struct bitstream_reader::BitBuffer

pub struct BitBuffer<E> where
    E: Endianness,  { /* fields omitted */ }

Buffer that allows reading integers of arbitrary bit length and non byte-aligned integers

Examples

use bitstream_reader::{BitBuffer, LittleEndian, Result};

let bytes = vec![
    0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
    0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
];
let buffer = BitBuffer::new(bytes, LittleEndian);
// read 7 bits as u8, starting from bit 3
let result: u8 = buffer.read_int(3, 7)?;

Methods

impl<E> BitBuffer<E> where
    E: Endianness, 

pub fn new(bytes: Vec<u8>, _endianness: E) -> Self

Create a new BitBuffer from a byte vector

Examples

use bitstream_reader::{BitBuffer, LittleEndian};

let bytes = vec![
    0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
    0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
];
let buffer = BitBuffer::new(bytes, LittleEndian);

impl<E> BitBuffer<E> where
    E: Endianness, 

pub fn bit_len(&self) -> usize

The available number of bits in the buffer

pub fn byte_len(&self) -> usize

The available number of bytes in the buffer

pub fn read_bool(&self, position: usize) -> Result<bool>

Read a single bit from the buffer as boolean

Errors

• ReadError::NotEnoughData: not enough bits available in the buffer

Examples

let result = buffer.read_bool(5)?;
assert_eq!(result, true);

pub fn read_int<T>(&self, position: usize, count: usize) -> Result<T> where
    T: PrimInt + BitOrAssign + IsSigned + UncheckedPrimitiveInt, 

Read a sequence of bits from the buffer as integer

Errors

• ReadError::NotEnoughData: not enough bits available in the buffer
• ReadError::TooManyBits: to many bits requested for the chosen integer type

Examples

let result = buffer.read_int::<u16>(10, 9)?;
assert_eq!(result, 0b100_0110_10);

pub unsafe fn read_int_unchecked<T>(&self, position: usize, count: usize) -> T where
    T: PrimInt + BitOrAssign + IsSigned + UncheckedPrimitiveInt, 

Read a sequence of bits from the buffer as integer without doing any bounds checking

Safety

This method will result in undefined behaviour when trying to read outside the bounds of the buffer, this method should only be used if performance is critical and bounds check has been done seperatelly.

Otherwise the safe read_int should be used.

Errors

• ReadError::NotEnoughData: not enough bits available in the buffer
• ReadError::TooManyBits: to many bits requested for the chosen integer type

Examples

let result = buffer.read_int::<u16>(10, 9)?;
assert_eq!(result, 0b100_0110_10);

pub fn read_bytes(&self, position: usize, byte_count: usize) -> Result<Vec<u8>>

Read a series of bytes from the buffer

Errors

• ReadError::NotEnoughData: not enough bits available in the buffer

Examples

assert_eq!(buffer.read_bytes(5, 3)?, &[0b0_1010_101, 0b0_1100_011, 0b1_1001_101]);
assert_eq!(buffer.read_bytes(0, 8)?, &[
    0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
    0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
]);

pub fn read_string(
    &self,
    position: usize,
    byte_len: Option<usize>
) -> Result<String>

Read a series of bytes from the buffer as string

You can either read a fixed number of bytes, or a dynamic length null-terminated string

Features

To disable the overhead of checking if the read bytes are valid you can enable the unchecked_utf8 feature of the crate to use String::from_utf8_unchecked instead of String::from_utf8 to create the string from the read bytes.

Errors

• ReadError::NotEnoughData: not enough bits available in the buffer
• ReadError::Utf8Error: the read bytes are not valid utf8

Examples

// Fixed length string
assert_eq!(buffer.read_string(0, Some(13))?, "Hello world".to_owned());
// fixed length with null padding
assert_eq!(buffer.read_string(0, Some(16))?, "Hello world".to_owned());
// null terminated
assert_eq!(buffer.read_string(0, None)?, "Hello world".to_owned());

pub fn read_float<T>(&self, position: usize) -> Result<T> where
    T: Float + UncheckedPrimitiveFloat, 

Read a sequence of bits from the buffer as float

Errors

• ReadError::NotEnoughData: not enough bits available in the buffer

Examples

let result = buffer.read_float::<f32>(10)?;

Trait Implementations

impl<E: Endianness> Clone for BitBuffer<E>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<E: Endianness> From<Vec<u8>> for BitBuffer<E>

fn from(bytes: Vec<u8>) -> Self

Performs the conversion.

impl<E: Endianness> From<BitBuffer<E>> for BitStream<E>

fn from(buffer: BitBuffer<E>) -> Self

Performs the conversion.

impl<E: Endianness> Debug for BitBuffer<E>

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

Formats the value using the given formatter.