dsi_bitstream/impls/
mod.rs

1/*
2 * SPDX-FileCopyrightText: 2023 Tommaso Fontana
3 * SPDX-FileCopyrightText: 2023 Inria
4 * SPDX-FileCopyrightText: 2023 Sebastiano Vigna
5 *
6 * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
7 */
8
9/*!
10
11Implementations of bit and word (seekable) streams.
12
13Implementations of bit streams read from word streams, that is,
14implementations of [`WordRead`](crate::traits::WordRead) and
15[`WordWrite`](crate::traits::WordWrite). If you have a standard
16[`Read`](std::io::Read) or [`Write`](std::io::Write) byte stream
17you can wrap it into a [`WordAdapter`] to turn it into a word stream.
18
19In instead you want to read or write words directly from memory, you can use
20[`MemWordReader`] and [`MemWordWriterVec`]/[`MemWordWriterSlice`],
21which read from a slice and write to a vector/slice.
22
23In all cases, you must specify a word type, which is the type of the words
24you want to read or write. In the case of [`WordAdapter`], the word type
25is arbitrary; in the case of [`MemWordReader`] and
26[`MemWordWriterVec`]/[`MemWordWriterSlice`],
27it must match the type of the elements of the slice or vector,
28and will be usually filled in by type inference.
29
30Once you have a way to read or write by words, you can use [`BufBitReader`] and
31[`BufBitWriter`] to read or write bits. Both have a statically
32selectable endianness and use an internal bit buffer to store bits that are not
33yet read or written. In the case of [`BufBitReader`], the bit buffer is
34twice large as the word type, so we suggest to use a type that is half of `usize` as word type,
35whereas in the case of [`BufBitWriter`] the bit buffer is as large as the word,
36so we suggest to use `usize` as word type.
37
38[`BitReader`] reads memory directly, without using a bit buffer, but it is
39usually significantly slower than [`BufBitReader`].
40
41If you want to optimize these choices for your architecture, we suggest to
42run the benchmarks in the `benchmarks` directory.
43
44## Examples
45
46### Reading from a file
47
48```rust
49# fn main() -> Result<(), Box<dyn std::error::Error>> {
50use dsi_bitstream::prelude::*;
51use std::io::BufReader;
52
53let file = std::fs::File::open("README.md")?;
54// Adapt to word type u32, select little endianness
55let mut reader = BufBitReader::<LE, _>::new(WordAdapter::<u32, _>::new(BufReader::new(file)));
56reader.read_gamma()?;
57# Ok(())
58# }
59```
60
61### Writing to and reading from a vector
62
63```rust
64# fn main() -> Result<(), Box<dyn std::error::Error>> {
65use dsi_bitstream::prelude::*;
66
67let mut v: Vec<u64> = vec![];
68// Automatically chooses word type u64, select big endianness
69let mut writer = BufBitWriter::<BE, _>::new(MemWordWriterVec::new(&mut v));
70writer.write_gamma(42)?;
71writer.flush()?;
72drop(writer); // We must drop the writer release the borrow on v
73
74let mut reader = BufBitReader::<BE, _>::new(MemWordReader::new(&v));
75assert_eq!(reader.read_gamma()?, 42);
76# Ok(())
77# }
78```
79
80*/
81
82mod mem_word_reader;
83pub use mem_word_reader::*;
84
85mod mem_word_writer;
86pub use mem_word_writer::*;
87
88#[cfg(feature = "std")]
89mod word_adapter;
90#[cfg(feature = "std")]
91pub use word_adapter::*;
92
93mod bit_reader;
94pub use bit_reader::BitReader;
95
96mod buf_bit_reader;
97pub use buf_bit_reader::BufBitReader;
98
99mod buf_bit_writer;
100pub use buf_bit_writer::BufBitWriter;
dsi_bitstream/impls/mod.rs

dsi_bitstream/impls/
mod.rs
