Struct BufBitReader 

pub struct BufBitReader<E: Endianness, WR: WordRead, RP: ReadParams = DefaultReadParams>
where
    WR::Word: DoubleType,
{ /* private fields */ }

An implementation of BitRead and BitSeek for a WordRead and a WordSeek.

This implementation uses a bit buffer to store bits that are not yet read. The buffer is sized as twice the word size of the underlying WordRead. Typically, the best choice is to have a buffer that is sized as usize, which means that the word of the underlying WordRead should be half of that (i.e., u32 for a 64-bit architecture). However, results will vary depending on the CPU.

The peek word is equal to the bit buffer. The value returned by peek_bits contains at least as many bits as the word size (extended with zeros beyond end of stream): a peek is served by at most one refill, so only one word of peekable bits can be guaranteed.

The convenience functions from_path and from_file (requiring the std feature) create a BufBitReader around a buffered file reader.

This implementation is usually faster than BitReader.

The additional type parameter RP is used to select the parameters for the instantaneous codes, but the casual user should be happy with the default value. See ReadParams for more details.

For additional flexibility, when the std feature is enabled, this structure implements std::io::Read. Note that because of coherence rules it is not possible to implement std::io::Read for a generic BitRead.

Implementations

impl<E: Endianness, WR: WordRead, RP: ReadParams> BufBitReader<E, WR, RP>

where WR::Word: DoubleType,

pub const fn new(backend: WR) -> Self

Creates a new BufBitReader around a WordRead.

Examples

use dsi_bitstream::prelude::*;
let words: [u32; 2] = [0x0043b59f, 0xccf16077];
let word_reader = MemWordReader::new_inf(&words);
let mut buf_bit_reader = <BufBitReader<BE, _>>::new(word_reader);

pub fn into_inner(self) -> WR

Consumes this reader and returns the underlying WordRead.

Trait Implementations

impl<WR: WordRead, RP: ReadParams> BitRead<BigEndian> for BufBitReader<BE, WR, RP>

where WR::Word: DoubleType,

const PEEK_BITS: usize

The number of bits that peek_bits is guaranteed to return successfully (with zero-extended EOF).

type Error = <WR as WordRead>::Error

type PeekWord = <<WR as WordRead>::Word as DoubleType>::DoubleType

The type we can read from the stream without advancing.

fn peek_bits(&mut self, n_bits: usize) -> Result<Self::PeekWord, Self::Error>

Peeks at n bits without advancing the stream position. n must be nonzero, and at most Self::PEEK_BITS.

fn read_bits(&mut self, num_bits: usize) -> Result<u64, Self::Error>

Reads num_bits bits and returns them in the lowest bits.

fn read_unary(&mut self) -> Result<u64, Self::Error>

Reads a unary code.

fn skip_bits(&mut self, n_bits: usize) -> Result<(), Self::Error>

Skip n bits from the stream.

fn copy_to<F: Endianness, W: BitWrite<F>>( &mut self, bit_write: &mut W, n: u64, ) -> Result<(), CopyError<Self::Error, W::Error>>

Copy bits from self to a BitWrite stream.

impl<WR: WordRead, RP: ReadParams> BitRead<LittleEndian> for BufBitReader<LE, WR, RP>

where WR::Word: DoubleType,

const PEEK_BITS: usize

The number of bits that peek_bits is guaranteed to return successfully (with zero-extended EOF).

type Error = <WR as WordRead>::Error

type PeekWord = <<WR as WordRead>::Word as DoubleType>::DoubleType

The type we can read from the stream without advancing.

fn peek_bits(&mut self, n_bits: usize) -> Result<Self::PeekWord, Self::Error>

Peeks at n bits without advancing the stream position. n must be nonzero, and at most Self::PEEK_BITS.

fn read_bits(&mut self, num_bits: usize) -> Result<u64, Self::Error>

Reads num_bits bits and returns them in the lowest bits.

fn read_unary(&mut self) -> Result<u64, Self::Error>

Reads a unary code.

fn skip_bits(&mut self, n_bits: usize) -> Result<(), Self::Error>

Skip n bits from the stream.

fn copy_to<F: Endianness, W: BitWrite<F>>( &mut self, bit_write: &mut W, n: u64, ) -> Result<(), CopyError<Self::Error, W::Error>>

Copy bits from self to a BitWrite stream.

impl<WR: WordRead + WordSeek<Error = <WR as WordRead>::Error>, RP: ReadParams> BitSeek for BufBitReader<BE, WR, RP>

where WR::Word: DoubleType,

type Error = <WR as WordSeek>::Error

fn bit_pos(&mut self) -> Result<u64, Self::Error>

Gets the current position in bits from the start of the stream.

fn set_bit_pos(&mut self, bit_index: u64) -> Result<(), Self::Error>

Sets the current position in bits from the start of the stream to bit_pos.

impl<WR: WordRead + WordSeek<Error = <WR as WordRead>::Error>, RP: ReadParams> BitSeek for BufBitReader<LE, WR, RP>

where WR::Word: DoubleType,

type Error = <WR as WordSeek>::Error

fn bit_pos(&mut self) -> Result<u64, Self::Error>

Gets the current position in bits from the start of the stream.

fn set_bit_pos(&mut self, bit_index: u64) -> Result<(), Self::Error>

Sets the current position in bits from the start of the stream to bit_pos.

impl<E: Endianness, WR: WordRead + Clone, RP: ReadParams> Clone for BufBitReader<E, WR, RP>

where WR::Word: DoubleType,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E: Debug + Endianness, WR: Debug + WordRead, RP: Debug + ReadParams> Debug for BufBitReader<E, WR, RP>

where WR::Word: DoubleType,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<WR: WordRead<Word: DoubleType>> DeltaRead<BigEndian> for BufBitReader<BigEndian, WR, DefaultReadParams>

fn read_delta(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead<Word: DoubleType>> DeltaRead<LittleEndian> for BufBitReader<LittleEndian, WR, DefaultReadParams>

fn read_delta(&mut self) -> Result<u64, Self::Error>

impl<E: Endianness, WR, RP: ReadParams> FlatType for BufBitReader<E, WR, RP>

where WR::Word: DoubleType, WR: MemSize + FlatType + WordRead, <<WR as WordRead>::Word as DoubleType>::DoubleType: MemSize + FlatType, usize: MemSize + FlatType, PhantomData<(E, RP)>: MemSize + FlatType,

type Flat = False

Whether the type is flat (True) or not (False).

impl<WR: WordRead<Word: DoubleType>> GammaRead<BigEndian> for BufBitReader<BigEndian, WR, DefaultReadParams>

fn read_gamma(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead<Word: DoubleType>> GammaRead<LittleEndian> for BufBitReader<LittleEndian, WR, DefaultReadParams>

fn read_gamma(&mut self) -> Result<u64, Self::Error>

impl<E: Endianness, WR, RP: ReadParams> MemDbgImpl for BufBitReader<E, WR, RP>

where WR::Word: DoubleType, WR: MemDbgImpl + FlatType + WordRead, <<WR as WordRead>::Word as DoubleType>::DoubleType: MemDbgImpl + FlatType, usize: MemDbgImpl + FlatType, PhantomData<(E, RP)>: MemDbgImpl + FlatType,

fn _mem_dbg_rec_on( &self, _memdbg_writer: &mut impl Write, _memdbg_total_size: usize, _memdbg_max_depth: usize, _memdbg_prefix: &mut String, _memdbg_is_last: bool, _memdbg_flags: DbgFlags, _memdbg_refs: &mut HashSet<usize>, ) -> Result

Recursively displays the fields of self below the current line.

fn _mem_dbg_depth_on( &self, writer: &mut impl Write, total_size: usize, max_depth: usize, prefix: &mut String, field_name: Option<&str>, is_last: bool, padded_size: usize, flags: DbgFlags, dbg_refs: &mut HashSet<usize>, ) -> Result<(), Error>

Displays self at the given depth without any reference-address annotation; forwards to _mem_dbg_depth_on_impl with RefDisplay::None.

fn _mem_dbg_depth_on_impl( &self, writer: &mut impl Write, total_size: usize, max_depth: usize, prefix: &mut String, field_name: Option<&str>, is_last: bool, padded_size: usize, flags: DbgFlags, dbg_refs: &mut HashSet<usize>, ref_display: RefDisplay, ) -> Result<(), Error>

Internal implementation for depth display.

impl<E: Endianness, WR, RP: ReadParams> MemSize for BufBitReader<E, WR, RP>

where WR::Word: DoubleType, WR: MemSize + FlatType + WordRead, <<WR as WordRead>::Word as DoubleType>::DoubleType: MemSize + FlatType, usize: MemSize + FlatType, PhantomData<(E, RP)>: MemSize + FlatType,

fn mem_size_rec( &self, _memsize_flags: SizeFlags, _memsize_refs: &mut HashMap<usize, usize>, ) -> usize

Recursive implementation that tracks visited references for deduplication.

fn mem_size(&self, flags: SizeFlags) -> usize

Returns the (recursively computed) overall memory size of the structure in bytes.

impl<WR: WordRead<Word: DoubleType>> OmegaRead<BigEndian> for BufBitReader<BigEndian, WR, DefaultReadParams>

fn read_omega(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead<Word: DoubleType>> OmegaRead<LittleEndian> for BufBitReader<LittleEndian, WR, DefaultReadParams>

fn read_omega(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead<Word: DoubleType>> PiRead<BigEndian> for BufBitReader<BigEndian, WR, DefaultReadParams>

fn read_pi(&mut self, k: usize) -> Result<u64, Self::Error>

fn read_pi2(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead<Word: DoubleType>> PiRead<LittleEndian> for BufBitReader<LittleEndian, WR, DefaultReadParams>

fn read_pi(&mut self, k: usize) -> Result<u64, Self::Error>

fn read_pi2(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead, RP: ReadParams> Read for BufBitReader<LE, WR, RP>

where WR::Word: DoubleType,

Available on crate feature std only.

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Note that this implementation transfers data in 8-byte chunks, and a WordRead backend error is not atomic with respect to the chunk: near the end of the stream a partial chunk may be consumed and then discarded, so up to 7 trailing bytes can be unreachable through this interface when the destination buffer length is a multiple of 8. Moreover, the backend error type cannot distinguish end of stream from a backend failure, so reading past the last available byte fails with std::io::ErrorKind::UnexpectedEof instead of returning Ok(0).

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_, u8>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact( &mut self, cursor: BorrowedCursor<'_, u8>, ) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

fn read_le<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in little-endian order.

fn read_be<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in big-endian order.

impl<WR: WordRead, RP: ReadParams> Read for BufBitReader<BE, WR, RP>

where WR::Word: DoubleType,

Available on crate feature std only.

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Note that this implementation transfers data in 8-byte chunks, and a WordRead backend error is not atomic with respect to the chunk: near the end of the stream a partial chunk may be consumed and then discarded, so up to 7 trailing bytes can be unreachable through this interface when the destination buffer length is a multiple of 8. Moreover, the backend error type cannot distinguish end of stream from a backend failure, so reading past the last available byte fails with std::io::ErrorKind::UnexpectedEof instead of returning Ok(0).

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_, u8>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact( &mut self, cursor: BorrowedCursor<'_, u8>, ) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

fn read_le<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in little-endian order.

fn read_be<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

🔬This is a nightly-only experimental API. (read_le)

Read and return a type (e.g. an integer) in big-endian order.

impl<WR: WordRead<Word: DoubleType>> ZetaRead<BigEndian> for BufBitReader<BigEndian, WR, DefaultReadParams>

fn read_zeta(&mut self, k: usize) -> Result<u64, Self::Error>

fn read_zeta3(&mut self) -> Result<u64, Self::Error>

impl<WR: WordRead<Word: DoubleType>> ZetaRead<LittleEndian> for BufBitReader<LittleEndian, WR, DefaultReadParams>

fn read_zeta(&mut self, k: usize) -> Result<u64, Self::Error>

fn read_zeta3(&mut self) -> Result<u64, Self::Error>