Struct BitReadStream

pub struct BitReadStream<'a, E>
where
    E: Endianness,
{ /* private fields */ }

Stream that provides an easy way to iterate trough a BitBuffer

Examples

use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian};

let bytes = vec![
    0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
    0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
];
let buffer = BitReadBuffer::new(&bytes, LittleEndian);
let mut stream = BitReadStream::new(buffer);

Implementations

impl<'a, E> BitReadStream<'a, E>

where E: Endianness,

pub fn new(buffer: BitReadBuffer<'a, E>) -> Self

Create a new stream from a BitBuffer

Examples

use bitbuffer::{BitReadBuffer, BitReadStream, LittleEndian};

let bytes = vec![
    0b1011_0101, 0b0110_1010, 0b1010_1100, 0b1001_1001,
    0b1001_1001, 0b1001_1001, 0b1001_1001, 0b1110_0111
];
let buffer = BitReadBuffer::new(&bytes, LittleEndian);
let mut stream = BitReadStream::new(buffer);

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

Read a single bit from the stream as boolean

Errors

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

Examples

assert_eq!(stream.read_bool()?, true);
assert_eq!(stream.read_bool()?, false);
assert_eq!(stream.pos(), 2);

pub fn read_int<T>(&mut self, count: usize) -> Result<T>

where T: PrimInt + BitOrAssign + IsSigned + UncheckedPrimitiveInt + WrappingSub,

Read a sequence of bits from the stream as integer

Errors

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

Examples

assert_eq!(stream.read_int::<u16>(3)?, 0b101);
assert_eq!(stream.read_int::<u16>(3)?, 0b110);
assert_eq!(stream.pos(), 6);

pub fn read_float<T>(&mut self) -> Result<T>

where T: Float + UncheckedPrimitiveFloat,

Read a sequence of bits from the stream as float

Errors

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

Examples

let result = stream.read_float::<f32>()?;
assert_eq!(stream.pos(), 32);

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

Read a series of bytes from the stream

Errors

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

Examples

let bytes = vec![
assert_eq!(stream.read_bytes(3)?.to_vec(), &[0b1011_0101, 0b0110_1010, 0b1010_1100]);
assert_eq!(stream.pos(), 24);

pub fn read_string(&mut self, byte_len: Option<usize>) -> Result<Cow<'a, str>>

Read a series of bytes from the stream as utf8 string

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

Errors

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

Examples

// Fixed length string
stream.set_pos(0);
assert_eq!(stream.read_string(Some(11))?, "Hello world".to_owned());
assert_eq!(11 * 8, stream.pos());
// fixed length with null padding
stream.set_pos(0);
assert_eq!(stream.read_string(Some(16))?, "Hello world".to_owned());
assert_eq!(16 * 8, stream.pos());
// null terminated
stream.set_pos(0);
assert_eq!(stream.read_string(None)?, "Hello world".to_owned());
assert_eq!(12 * 8, stream.pos()); // 1 more for the terminating null byte

pub fn read_bits(&mut self, count: usize) -> Result<Self>

Read a sequence of bits from the stream as a BitStream

Errors

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

Examples

let mut bits = stream.read_bits(3)?;
assert_eq!(stream.pos(), 3);
assert_eq!(bits.pos(), 0);
assert_eq!(bits.bit_len(), 3);
assert_eq!(stream.read_int::<u8>(3)?, 0b110);
assert_eq!(bits.read_int::<u8>(3)?, 0b101);
assert_eq!(true, bits.read_int::<u8>(1).is_err());

pub fn skip_bits(&mut self, count: usize) -> Result<()>

Skip a number of bits in the stream

Errors

• ReadError::NotEnoughData: not enough bits available in the stream to skip

Examples

stream.skip_bits(3)?;
assert_eq!(stream.pos(), 3);
assert_eq!(stream.read_int::<u8>(3)?, 0b110);

pub fn align(&mut self) -> Result<usize>

Align the stream on the next byte and returns the amount of bits read

Errors

• ReadError::NotEnoughData: not enough bits available in the stream to skip

Examples

stream.align()?;
assert_eq!(stream.pos(), 0);

stream.skip_bits(3)?;
assert_eq!(stream.pos(), 3);
stream.align();
assert_eq!(stream.pos(), 8);
assert_eq!(stream.read_int::<u8>(4)?, 0b1010);

pub fn set_pos(&mut self, pos: usize) -> Result<()>

Set the position of the stream

Errors

• ReadError::IndexOutOfBounds: new position is outside the bounds of the stream

Examples

stream.set_pos(3)?;
assert_eq!(stream.pos(), 3);
assert_eq!(stream.read_int::<u8>(3)?, 0b110);

pub fn bit_len(&self) -> usize

Get the length of the stream in bits

Examples

assert_eq!(stream.bit_len(), 64);

pub fn pos(&self) -> usize

Get the current position in the stream

Examples

assert_eq!(stream.pos(), 0);
stream.skip_bits(5)?;
assert_eq!(stream.pos(), 5);

pub fn bits_left(&self) -> usize

Get the number of bits left in the stream

Examples

assert_eq!(stream.bits_left(), 64);
stream.skip_bits(5)?;
assert_eq!(stream.bits_left(), 59);

pub fn read<T: BitRead<'a, E>>(&mut self) -> Result<T>

Read a value based on the provided type

Examples

let int: u8 = stream.read()?;
assert_eq!(int, 0b1011_0101);
let boolean: bool = stream.read()?;
assert_eq!(false, boolean);

use bitbuffer::BitRead;
#[derive(BitRead, Debug, PartialEq)]
struct ComplexType {
    first: u8,
    #[size = 15]
    second: u16,
    third: bool,
}
let data: ComplexType = stream.read()?;
assert_eq!(data, ComplexType {
    first: 0b1011_0101,
    second: 0b010_1100_0110_1010,
    third: true,
});

pub fn read_sized<T: BitReadSized<'a, E>>(&mut self, size: usize) -> Result<T>

Read a value based on the provided type and size

The meaning of the size parameter differs depending on the type that is being read

Examples

let int: u8 = stream.read_sized(7)?;
assert_eq!(int, 0b011_0101);

let data: Vec<u16> = stream.read_sized(3)?;
assert_eq!(data, vec![0b0110_1010_1011_0101, 0b1001_1001_1010_1100, 0b1001_1001_1001_1001]);

pub fn peek<T: BitRead<'a, E>>(&mut self) -> Result<T>

Read a value based on the provided type without advancing the stream

pub fn peek_sized<T: BitReadSized<'a, E>>(&mut self, size: usize) -> Result<T>

Read a value based on the provided type and size without advancing the stream

pub fn check_read(&self, count: usize) -> Result<bool>

Check if we can read a number of bits from the stream

pub fn to_owned(&self) -> BitReadStream<'static, E>

Create an owned copy of this stream

Trait Implementations

impl<'a, E: Endianness> BitReadSized<'a, E> for BitReadStream<'a, E>

fn read(stream: &mut BitReadStream<'a, E>, size: usize) -> Result<Self>

Read the type from stream

fn bit_size_sized(size: usize) -> Option<usize>

The number of bits that will be read or None if the number of bits will change depending on the bit stream

fn skip(stream: &mut BitReadStream<'a, E>, size: usize) -> Result<()>

Skip the type

impl<E: Endianness> BitWrite<E> for BitReadStream<'_, E>

fn write(&self, stream: &mut BitWriteStream<'_, E>) -> Result<()>

Write the type to stream

impl<E: Endianness> BitWriteSized<E> for BitReadStream<'_, E>

fn write_sized( &self, stream: &mut BitWriteStream<'_, E>, len: usize, ) -> Result<()>

Write the type to stream

impl<E: Endianness> Clone for BitReadStream<'_, E>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, E> Debug for BitReadStream<'a, E>

where E: Endianness + Debug,

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

Formats the value using the given formatter.

impl<'a, E: Endianness> From<&'a [u8]> for BitReadStream<'a, E>

fn from(bytes: &'a [u8]) -> Self

Converts to this type from the input type.

impl<'a, E: Endianness> From<BitReadBuffer<'a, E>> for BitReadStream<'a, E>

fn from(buffer: BitReadBuffer<'a, E>) -> Self

Converts to this type from the input type.

impl<E: Endianness> PartialEq for BitReadStream<'_, E>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.