Crate bitstream_io

Traits and helpers for bitstream handling functionality

Bitstream readers are for reading signed and unsigned integer values from a stream whose sizes may not be whole bytes. Bitstream writers are for writing signed and unsigned integer values to a stream, also potentially un-aligned at a whole byte.

Both big-endian and little-endian streams are supported.

The only requirement for wrapped reader streams is that they must implement the Read trait, and the only requirement for writer streams is that they must implement the Write trait.

In addition, reader streams do not consume any more bytes from the underlying reader than necessary, buffering only a single partial byte as needed. Writer streams also write out all whole bytes as they are accumulated.

Readers and writers are also designed to work with integer types of any possible size. Many of Rust’s built-in integer types are supported by default.

Minimum Compiler Version

Beginning with version 2.4, the minimum compiler version has been updated to Rust 1.79.

The issue is that reading an excessive number of bits to a type which is too small to hold them, or writing an excessive number of bits from too small of a type, are always errors:

use std::io::{Read, Cursor};
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0; 10];
let mut r = BitReader::endian(Cursor::new(&data), BigEndian);
let x: Result<u32, _> = r.read(64);  // reading 64 bits to u32 always fails at runtime
assert!(x.is_err());

but those errors will not be caught until the program runs, which is less than ideal for the common case in which the number of bits is already known at compile-time.

But starting with Rust 1.79, we can now have read and write methods which take a constant number of bits and can validate the number of bits are small enough for the type being read/written at compile-time:

use std::io::{Read, Cursor};
use bitstream_io::{BigEndian, BitReader, BitRead};
let data = [0; 10];
let mut r = BitReader::endian(Cursor::new(&data), BigEndian);
let x: Result<u32, _> = r.read_in::<64, _>();  // doesn't compile at all

Since catching potential bugs at compile-time is preferable to encountering errors at runtime, this will hopefully be an improvement in the long run.

Migrating From Pre 1.0.0

There are now BitRead and BitWrite traits for bitstream reading and writing (analogous to the standard library’s Read and Write traits) which you will also need to import. The upside to this approach is that library consumers can now make functions and methods generic over any sort of bit reader or bit writer, regardless of the underlying stream byte source or endianness.

Re-exports

• pub use read::BitRead;
• pub use read::BitReader;
• pub use read::ByteRead;
• pub use read::ByteReader;
• pub use read::FromBitStream;
• pub use read::FromBitStreamWith;
• pub use read::FromByteStream;
• pub use read::FromByteStreamWith;
• pub use read::HuffmanRead;
• pub use write::BitCounter;
• pub use write::BitRecorder;
• pub use write::BitWrite;
• pub use write::BitWriter;
• pub use write::ByteWrite;
• pub use write::ByteWriter;
• pub use write::HuffmanWrite;
• pub use write::ToBitStream;
• pub use write::ToBitStreamWith;
• pub use write::ToByteStream;
• pub use write::ToByteStreamWith;

Modules

• huffman
  Traits and implementations for reading or writing Huffman codes from or to a stream.
• read
  Traits and implementations for reading bits from a stream.
• write
  Traits and implementations for writing bits to a stream.

Structs

• BigEndian
  Big-endian, or most significant bits first
• BitQueue
  A queue for efficiently pushing bits onto a value and popping them off a value.
• LittleEndian
  Little-endian, or least significant bits first

Traits

• Endianness
  A stream’s endianness, or byte order, for determining how bits should be read.
• Numeric
  This trait extends many common integer types (both unsigned and signed) with a few trivial methods so that they can be used with the bitstream handling traits.
• Primitive
  A trait intended for simple fixed-length primitives (such as ints and floats) which allows them to be read and written to streams of different endiannesses verbatim.
• SignedNumeric
  This trait extends many common signed integer types so that they can be used with the bitstream handling traits.

Type Aliases

• BE
  Big-endian, or most significant bits first
• LE
  Little-endian, or least significant bits first