bitstream-io

bitstream-io is a Rust library for reading or writing binary values to or from streams that may not be aligned at a whole byte. It wraps around any stream implementing the standard Read or Write traits and supports a wide array of integer types as containers for those bit-level values.

The library handles both big-endian and little-endian bit ordering, provides byte-aligned convenience readers and writers, and includes Huffman coding support. It leans on Rust’s const generics and compile-time assertions to catch a class of bit-width errors at build time rather than at runtime, making it a solid foundation for codecs and binary file-format parsers.

What You Get

• Bit-level BitReader and BitWriter over any Read/Write stream
• Both big-endian and little-endian bit orderings
• Reading and writing arbitrary-width integers into standard Rust integer containers
• Byte-aligned reader/writer helpers plus Huffman coding support
• Compile-time checks on bit widths via const generics and const assertions

Common Use Cases

• Implementing audio, image, or video codecs with non-byte-aligned fields
• Parsing or emitting compressed and binary file formats
• Encoding and decoding bit-packed protocol or container formats
• Building Huffman-coded data streams

Under The Hood

Architecture - The crate centers on read.rs and write.rs, which define the BitReader/BitWriter types generic over an endianness marker and the wrapped stream. byte_io.rs adds byte-aligned convenience wrappers, huffman.rs implements Huffman tree reading/writing, and lib.rs ties the traits together. Bit widths are frequently expressed as const generic parameters so the compiler can validate them.

Tech Stack - Pure Rust, dual-licensed Apache-2.0 OR MIT, minimum rustc 1.79 (to use compile-time const block assertions). It builds on only the standard library’s Read/Write traits, keeping dependencies minimal, and ships integration tests under tests/ plus runnable examples.

Code Quality - The project is mature and stable, authored primarily by a single long-term maintainer with a handful of contributors. It carries a documented CHANGES.md, example programs, and a test suite, and it deliberately pushes error detection to compile time via const assertions to reduce runtime surprises.

API Design - The API mirrors Rust’s standard I/O ergonomics: wrap a stream in a BitReader/BitWriter, then read or write typed values with explicit bit counts. Endianness is a type parameter rather than a runtime flag, so the wrong ordering cannot be mixed accidentally, and the interface stays small and predictable.