Struct bitstream_reader::BitStream

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

Stream that provides an easy way to iterate trough a BitBuffer

Examples

use bitstream_reader::{BitBuffer, BitStream, 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);
let mut stream = BitStream::new(buffer);

Methods

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

pub fn new(buffer: BitBuffer<E>) -> Self

Create a new stream for a BitBuffer

Examples

use bitstream_reader::{BitBuffer, BitStream, 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);
let mut stream = BitStream::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, 

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<Vec<u8>>

Read a series of bytes from the stream

Errors

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

Examples

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

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

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(&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(3)?;
assert_eq!(stream.pos(), 3);
assert_eq!(stream.read_int::<u8>(3)?, 0b110);

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(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(5)?;
assert_eq!(stream.bits_left(), 59);

pub fn read<T: BitRead<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 bitstream_reader::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<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]);

Trait Implementations

impl<E: Endianness> BitReadSized<E> for BitStream<E>

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

Read the type from stream

impl<E: Endianness> BitSizeSized for BitStream<E>

fn bit_size(size: usize) -> usize

How many bits are required to read this type

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

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

Performs the conversion.

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

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

Performs the conversion.

impl<E: Endianness> Clone for BitStream<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: Debug> Debug for BitStream<E> where
    E: Endianness, 

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

Formats the value using the given formatter.