endio_bit/
lib.rs

1/*!
2	## Bit-level reading and writing
3
4	`std::io::{Read, Write}` only allow reading and writing on the byte-level. This is not sufficient when working with protocols that use single bits or use structs that are not multiples of 8 bits in size. This crate provides wrappers for reading and writing, enabling bit-level I/O on any object implementing [`Read`]/[`Write`].
5
6	The wrappers are modeled after [`std::io::BufReader`] and [`std::io::BufWriter`], so the semantics and interface should be familiar and robust.
7
8	This crate is a minimal low-level abstraction focusing on bit-level I/O. I recommend using this crate together with [`endio`] if you also need byte-level I/O or (de-)serialization support. However, this crate is completely independent from [`endio`], and can be used standalone if you're only looking for `std::io` with bit support.
9
10	### Goals of this crate
11
12	- Reading and writing of single bits.
13	- Reading and writing of bits that aren't a multiple of 8.
14	- Reading and writing even if the underlying object is bitshifted.
15	- Support for [bit endianness](https://en.wikipedia.org/wiki/Bit_numbering#Most-_vs_least-significant_bit_first) conversion/distinction.
16
17	### Non-goals of this crate
18
19	- Data type (de-)serialization. If you need this, use [`endio`] in combination with this crate.
20	- [Byte endianness](https://en.wikipedia.org/wiki/Endianness) conversion/distinction. If you need this, use [`endio`] in combination with this crate.
21
22	### Comparison with other crates
23
24	Bit-level I/O is a common problem, and there are numerous crates on crates.io attempting to provide solutions. However, I haven't been able to find one that is completely satisfactory. Here's a list of related crates and how they differ from this one:
25
26	- `av-bitstream` - Includes (de-)serialization and byte endianness. No bit-level writing. Undocumented.
27
28	- `bit-io` - Does not implement `std::io::{Read, Write}`. No support for bit endianness. Undocumented.
29
30	- `bitio` - No support for writing. No support for bit endianness.
31
32	- `bitstream`, `bitstream_reader`, `bitter` - Include (de-)serialization and byte endianness. No support for writing.
33
34	- `bitstream-io` - Includes (de-)serialization and byte endianness. Includes Huffman trees for some reason. Does not implement `std::io::{Read, Write}`.
35
36	- `bitstream-rs` - Only has support for reading and writing single bits. Does not implement `std::io::{Read, Write}`.
37
38	- `bitreader` - Only has support for reading. Includes deserialization in forced big endian, no little endian support.
39
40	Therefore there is an opportunity to improve on the current library situation, which I hope to address through this crate.
41
42	[`std::io::BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
43	[`std::io::BufWriter`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html
44	[`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
45	[`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
46	[`endio`]: https://crates.io/crates/endio
47*/
48mod endian;
49mod read;
50mod write;
51
52pub use self::read::*;
53pub use self::write::*;
endio_bit/lib.rs

endio_bit/
lib.rs
