Module dsi_bitstream::impls
source · Expand description
Implementations of bit and word (seekable) streams.
Implementations of bit streams read from word streams, that is,
implementations of WordRead
and
WordWrite
. If you have a standard
Read
or Write
byte stream
you can wrap it into a WordAdapter
to turn it into a word stream.
In instead you want to read or write words directly from memory, you can use
MemWordReader
and MemWordWriterVec
/MemWordWriterSlice
,
which read from a slice and write to a vector/slice.
In all cases, you must specify a word type, which is the type of the words
you want to read or write. In the case of WordAdapter
, the word type
is arbitrary; in the case of MemWordReader
and
MemWordWriterVec
/MemWordWriterSlice
,
it must match the type of the elements of the slice or vector,
and will be usually filled in by type inference.
Once you have a way to read or write by words, you can use BufBitReader
and
BufBitWriter
to read or write bits. Both have a statically
selectable endianness and use an internal bit buffer to store bits that are not
yet read or written. In the case of BufBitReader
, the bit buffer is
twice large as the word type, so we suggest to use a type that is half of usize
as word type,
whereas in the case of BufBitWriter
the bit buffer is as large as the word,
so we suggest to use usize
as word type.
BitReader
reads memory directly, without using a bit buffer, but it is
usually significantly slower than BufBitReader
.
If you want to optimize these choices for your architecture, we suggest to
run the benchmarks in the benchmarks
directory.
§Examples
§Reading from a file
use dsi_bitstream::prelude::*;
use std::io::BufReader;
let file = std::fs::File::open("README.md")?;
// Adapt to word type u32, select little endianness
let mut reader = BufBitReader::<LE, _>::new(WordAdapter::<u32, _>::new(BufReader::new(file)));
reader.read_gamma()?;
§Writing to and reading from a vector
use dsi_bitstream::prelude::*;
let mut v: Vec<u64> = vec![];
// Automatically chooses word type u64, select big endianness
let mut writer = BufBitWriter::<BE, _>::new(MemWordWriterVec::new(&mut v));
writer.write_gamma(42)?;
writer.flush()?;
drop(writer); // We must drop the writer release the borrow on v
let mut reader = BufBitReader::<BE, _>::new(MemWordReader::new(&v));
assert_eq!(reader.read_gamma()?, 42);