Struct BitReader

pub struct BitReader<R, E: Endianness> { /* private fields */ }

For reading non-aligned bits from a stream of bytes in a given endianness.

This will read exactly as many whole bytes needed to return the requested number of bits. It may cache up to a single partial byte but no more.

Implementations

impl<R, E: Endianness> BitReader<R, E>

pub fn new(reader: R) -> BitReader<R, E>

Wraps a BitReader around something that implements Read

pub fn endian(reader: R, _endian: E) -> BitReader<R, E>

Wraps a BitReader around something that implements Read with the given endianness.

Examples found in repository

examples/flac-metadata-read.rs (line 94)

fn main() {
    // test FLAC file data
    let flac = include_bytes!("data/metadata-only.flac");

    let mut reader = BitReader::endian(flac.as_slice(), BigEndian);

    // stream marker
    assert_eq!(&reader.read_to::<[u8; 4]>().unwrap(), b"fLaC");

    // metadata block header
    assert_eq!(
        reader.parse::<BlockHeader>().unwrap(),
        BlockHeader {
            last_block: false,
            block_type: 0,
            block_size: 34
        }
    );

    // STREAMINFO block
    assert_eq!(
        dbg!(reader.parse::<Streaminfo>().unwrap()),
        Streaminfo {
            minimum_block_size: 4096,
            maximum_block_size: 4096,
            minimum_frame_size: 1542,
            maximum_frame_size: 8546,
            sample_rate: 44100,
            channels: NonZero::new(2).unwrap(),
            bits_per_sample: NonZero::new(16).unwrap(),
            total_samples: 304844,
            md5: *b"\xFA\xF2\x69\x2F\xFD\xEC\x2D\x5B\x30\x01\x76\xB4\x62\x88\x7D\x92",
        }
    );

    // metadata block header
    assert_eq!(
        dbg!(reader.parse::<BlockHeader>().unwrap()),
        BlockHeader {
            last_block: false,
            block_type: 4,
            block_size: 122
        }
    );

    // VORBIS_COMMENT block
    assert_eq!(
        dbg!(reader.parse::<VorbisComment>().unwrap()),
        VorbisComment {
            vendor: "reference libFLAC 1.1.4 20070213".to_string(),
            comment: vec![
                "title=2ch 44100  16bit".to_string(),
                "album=Test Album".to_string(),
                "artist=Assorted".to_string(),
                "tracknumber=1".to_string(),
            ],
        }
    );
}

pub fn into_reader(self) -> R

Unwraps internal reader and disposes of BitReader.

Warning

Any unread partial bits are discarded.

impl<R: Read, E: Endianness> BitReader<R, E>

pub fn reader(&mut self) -> Option<&mut R>

If stream is byte-aligned, provides mutable reference to internal reader. Otherwise returns None

pub fn aligned_reader(&mut self) -> &mut R

Returns byte-aligned mutable reference to internal reader.

Bytes aligns stream if it is not already aligned.

pub fn into_bytereader(self) -> ByteReader<R, E>

Converts BitReader to ByteReader in the same endianness.

Warning

Any unread partial bits are discarded.

pub fn bytereader(&mut self) -> Option<ByteReader<&mut R, E>>

If stream is byte-aligned, provides temporary ByteReader in the same endianness. Otherwise returns None

Warning

Any reader bits left over when ByteReader is dropped are lost.

impl<R, E> BitReader<R, E>

where E: Endianness, R: Read + Seek,

pub fn seek_bits(&mut self, from: SeekFrom) -> Result<u64>

Example

use std::io::{Read, Cursor, SeekFrom};
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0x00, 0xFF];
let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
assert_eq!(reader.position_in_bits().unwrap(), 0);

let pos = reader.seek_bits(SeekFrom::Start(5)).unwrap();
assert!(pos == 5 && 5 == reader.position_in_bits().unwrap());

let pos = reader.seek_bits(SeekFrom::Current(-2)).unwrap();
assert!(pos == 3 && 3 == reader.position_in_bits().unwrap());

let pos = reader.seek_bits(SeekFrom::End(5)).unwrap();
assert!(pos == 11 && 11 == reader.position_in_bits().unwrap());

pub fn position_in_bits(&mut self) -> Result<u64>

Example

use std::fs::read;
use std::io::{Read, Cursor, SeekFrom};
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0x00, 0xFF];
let mut reader = BitReader::endian(Cursor::new(&data), BigEndian);
assert_eq!(reader.position_in_bits().unwrap(), 0);

let _: i32 = reader.read_signed::<5, _>().unwrap();
assert_eq!(reader.position_in_bits().unwrap(), 5);

reader.read_bit().unwrap();
assert_eq!(reader.position_in_bits().unwrap(), 6);

Trait Implementations

impl<R: Read, E: Endianness> BitRead for BitReader<R, E>

fn skip(&mut self, bits: u32) -> Result<()>

Examples

use std::io::Read;
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0b10110111];
let mut reader = BitReader::endian(data.as_slice(), BigEndian);
assert!(reader.skip(3).is_ok());
assert_eq!(reader.read::<5, u8>().unwrap(), 0b10111);

use std::io::Read;
use bitstream_io::{LittleEndian, BitReader, BitRead};
let data = [0b10110111];
let mut reader = BitReader::endian(data.as_slice(), LittleEndian);
assert!(reader.skip(3).is_ok());
assert_eq!(reader.read::<5, u8>().unwrap(), 0b10110);

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

Example

use std::io::Read;
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = b"foobar";
let mut reader = BitReader::endian(data.as_slice(), BigEndian);
assert!(reader.skip(24).is_ok());
let mut buf = [0;3];
assert!(reader.read_bytes(&mut buf).is_ok());
assert_eq!(&buf, b"bar");

fn read_bit(&mut self) -> Result<bool>

Reads a single bit from the stream. true indicates 1, false indicates 0

fn read_unsigned_counted<const BITS: u32, U>( &mut self, bits: BitCount<BITS>, ) -> Result<U>

where U: UnsignedInteger,

Reads an unsigned value from the stream with the given number of bits.

fn read_unsigned<const BITS: u32, U>(&mut self) -> Result<U>

where U: UnsignedInteger,

Reads an unsigned value from the stream with the given constant number of bits.

fn read_signed_counted<const MAX: u32, S>( &mut self, bits: impl TryInto<SignedBitCount<MAX>>, ) -> Result<S>

where S: SignedInteger,

Reads a twos-complement signed value from the stream with the given number of bits.

fn read_signed<const BITS: u32, S>(&mut self) -> Result<S>

where S: SignedInteger,

Reads a twos-complement signed value from the stream with the given constant number of bits.

fn read_to<V>(&mut self) -> Result<V>

where V: Primitive,

Reads whole value from the stream whose size in bits is equal to its type’s size.

fn read_as_to<F, V>(&mut self) -> Result<V>

where F: Endianness, V: Primitive,

Reads whole value from the stream whose size in bits is equal to its type’s size in an endianness that may be different from the stream’s endianness.

fn read_unary<const STOP_BIT: u8>(&mut self) -> Result<u32>

Counts the number of bits in the stream until STOP_BIT and returns the amount read. STOP_BIT must be 0 or 1. Because this field is variably-sized and may be large, its output is always a u32 type.

fn byte_aligned(&self) -> bool

Returns true if the stream is aligned at a whole byte.

fn byte_align(&mut self)

Throws away all unread bit values until the next whole byte. Does nothing if the stream is already aligned.

fn read<const BITS: u32, I>(&mut self) -> Result<I>

where I: Integer,

Reads a signed or unsigned value from the stream with the given constant number of bits.

fn read_var<I>(&mut self, bits: u32) -> Result<I>

where I: Integer + Sized,

Reads a signed or unsigned value from the stream with the given variable number of bits.

fn read_count<const MAX: u32>(&mut self) -> Result<BitCount<MAX>>

Given a desired maximum value for a bit count, reads the necessary bits to fill up to that amount.

fn read_counted<const MAX: u32, I>(&mut self, bits: BitCount<MAX>) -> Result<I>

where I: Integer + Sized,

Reads a signed or unsigned value from the stream with the given number of bits.

fn read_unsigned_var<U>(&mut self, bits: u32) -> Result<U>

where U: UnsignedInteger,

Reads an unsigned value from the stream with the given number of bits.

fn read_signed_var<S>(&mut self, bits: u32) -> Result<S>

where S: SignedInteger,

Reads a twos-complement signed value from the stream with the given number of bits.

fn read_const<const BITS: u32, const VALUE: u32, E>( &mut self, err: E, ) -> Result<(), E>

where E: From<Error>,

Reads the given constant value from the stream with the given number of bits.

fn read_to_bytes<const SIZE: usize>(&mut self) -> Result<[u8; SIZE]>

👎Deprecated since 1.8.0: use read_to() method instead

Completely fills a whole buffer with bytes and returns it. If the stream is already byte-aligned, it will map to a faster read_exact call. Otherwise it will read bytes individually in 8-bit increments.

fn read_to_vec(&mut self, bytes: usize) -> Result<Vec<u8>>

Completely fills a vector of bytes and returns it. If the stream is already byte-aligned, it will map to a faster read_exact call. Otherwise it will read bytes individually in 8-bit increments.

fn parse<F: FromBitStream>(&mut self) -> Result<F, F::Error>

Parses and returns complex type

fn parse_with<'a, F: FromBitStreamWith<'a>>( &mut self, context: &F::Context, ) -> Result<F, F::Error>

Parses and returns complex type with context

fn read_huffman<T>(&mut self) -> Result<T::Symbol>

where T: FromBits,

Given a compiled Huffman tree, reads bits from the stream until the next symbol is encountered.

fn by_ref(&mut self) -> &mut Self

Creates a “by reference” adaptor for this BitRead

impl<R: Clone, E: Clone + Endianness> Clone for BitReader<R, E>

fn clone(&self) -> BitReader<R, E>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R: Debug, E: Debug + Endianness> Debug for BitReader<R, E>

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

Formats the value using the given formatter.