dsi-bitstream 0.9.2

/*
 * SPDX-FileCopyrightText: 2023 Tommaso Fontana
 * SPDX-FileCopyrightText: 2023 Inria
 * SPDX-FileCopyrightText: 2023 Sebastiano Vigna
 *
 * SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
 */

//! Implementations of bit and word (seekable) streams.
//!
//! Implementations of bit streams read from word streams, that is,
//! implementations of [`WordRead`](crate::traits::WordRead) and
//! [`WordWrite`](crate::traits::WordWrite). If you have a standard
//! [`Read`](std::io::Read) or [`Write`](std::io::Write) byte stream
//! you can wrap it into a [`WordAdapter`] to turn it into a word stream.
//!
//! If 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 as 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 `benches` directory.
//!
//! ## Examples
//!
//! ### Reading from a file
//!
//! ```rust
//! # #[cfg(not(feature = "std"))]
//! # fn main() {}
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn core::error::Error>> {
//! 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()?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Writing to and reading from a vector
//!
//! ```rust
//! # #[cfg(not(feature = "std"))]
//! # fn main() {}
//! # #[cfg(feature = "std")]
//! # fn main() -> Result<(), Box<dyn core::error::Error>> {
//! 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 to release the borrow on v
//!
//! let mut reader = BufBitReader::<BE, _>::new(MemWordReader::new_inf(&v));
//! assert_eq!(reader.read_gamma()?, 42);
//! # Ok(())
//! # }
//! ```

mod mem_word_reader;
pub use mem_word_reader::*;

mod mem_word_writer;
pub use mem_word_writer::*;

#[cfg(feature = "std")]
mod word_adapter;
#[cfg(feature = "std")]
pub use word_adapter::*;

mod bit_reader;
pub use bit_reader::BitReader;

pub mod buf_bit_reader;
pub use buf_bit_reader::BufBitReader;

pub mod buf_bit_writer;
pub use buf_bit_writer::BufBitWriter;