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# #[cfg(not(feature = "std"))]
50# fn main() {}
51# #[cfg(feature = "std")]
52# fn main() -> Result<(), Box<dyn std::error::Error>> {
53use dsi_bitstream::prelude::*;
54use std::io::BufReader;
55
56let file = std::fs::File::open("README.md")?;
57// Adapt to word type u32, select little endianness
58let mut reader = BufBitReader::<LE, _>::new(WordAdapter::<u32, _>::new(BufReader::new(file)));
59reader.read_gamma()?;
60# Ok(())
61# }
62```
63
64### Writing to and reading from a vector
65
66```rust
67# #[cfg(not(feature = "std"))]
68# fn main() {}
69# #[cfg(feature = "std")]
70# fn main() -> Result<(), Box<dyn std::error::Error>> {
71use dsi_bitstream::prelude::*;
72
73let mut v: Vec<u64> = vec![];
74// Automatically chooses word type u64, select big endianness
75let mut writer = BufBitWriter::<BE, _>::new(MemWordWriterVec::new(&mut v));
76writer.write_gamma(42)?;
77writer.flush()?;
78drop(writer); // We must drop the writer release the borrow on v
79
80let mut reader = BufBitReader::<BE, _>::new(MemWordReader::new(&v));
81assert_eq!(reader.read_gamma()?, 42);
82# Ok(())
83# }
84```
85
86*/
87
88mod mem_word_reader;
89pub use mem_word_reader::*;
90
91mod mem_word_writer;
92pub use mem_word_writer::*;
93
94#[cfg(feature = "std")]
95mod word_adapter;
96#[cfg(feature = "std")]
97pub use word_adapter::*;
98
99mod bit_reader;
100pub use bit_reader::BitReader;
101
102mod buf_bit_reader;
103pub use buf_bit_reader::BufBitReader;
104
105mod buf_bit_writer;
106pub use buf_bit_writer::BufBitWriter;
dsi_bitstream/impls/mod.rs

dsi_bitstream/impls/
mod.rs
