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

dsi_bitstream/impls/
mod.rs
