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

dsi_bitstream/impls/
mod.rs
