Module traits

Traits for operating on streams of bits.

We provide three bit-based traits, BitRead, BitWrite, and BitSeek, analogous to std::io::Read, std::io::Write, and std::io::Seek, respectively. They provide read/write operations on fixed-width blocks of bits and unary codes. More complex operations, such as reading instantaneous codes, are built on these basic traits.

The endianness of a bit stream specified by using the selector types BigEndian (AKA LE) and LittleEndian (AKA BE), which are the only implementations of the sealed marker trait Endianness.

The implementations we provide for these traits (e.g., BufBitReader) are based on WordRead, WordWrite, and WordSeek, which provide word-based operations, as reading or writing multiple bytes at a time is usually much faster than reading or writing single bytes, in particular when interacting with memory. For example, MemWordRead is a WordRead that reads word-by-word from a slice.

All traits have an internal error type Error, which usually propagates the error of the underlying backend. However, in some cases (e.g., MemWordRead with infinite zero extension) the error type is Infallible, in which case the compiler is able to perform several further optimizations.

Note that methods returning a Result will return a Result::Err variant only if there is an error in the underlying backend: errors in the parameters to the methods will generally result in panics.

Bit and byte order

The endianness parameter specifies at the same byte the endianness of the byte stream and of the bits in each byte: in the little-endian case, the first bit of the stream is the least significant bit of the first byte, while in the big-endian case it is the most significant bit of the first byte. Albeit in principle one can mix independently the two orders, having the same order for both bytes and bits is usually more convenient and makes for more efficient implementations.

Byte-level endianness is used to read memory word-by-word, greatly reducing the number of memory accesses when reading from slices. However, it is important to note that fixed-width values have thair least significant bit always stored at the lowest bit position, independently of endianness, as current CPUs always use big-endian bit order. In particular, reversing the order of the bits of each byte of a file containing a sequence of fixed-width integers or instantaneous codes will not in general yield a file containing the same sequence of integers or codes with the opposite endianness.

For example, if we write just the value 6 to a big-endian bit stream, we will get as first byte 110xxxxx, while if we write it to a little-endian bit stream we will obtain the byte xxxxx110. Clearly, reversing the order of the bits of each byte will not give the other byte.

See the codes module for a discussion on the impact of endianness on the encoding of instantaneous codes.

Structs

BigEndian

Selector type for big-endian streams.

LittleEndian

Selector type for little-endian streams.

Enums

CopyError

The error returned by the bit copy methods BitRead::copy_to and BitWrite::copy_from.

Traits

BitRead

Sequential, streaming bit-by-bit reads.

BitSeek

Seekability for BitRead and BitWrite streams.

BitWrite

Sequential, streaming bit-by-bit writes.

Endianness

Marker trait for endianness selector types.

Peek

Word

This is a trait alias for all the properties that we need words of memory read and wrote by either a WordRead or WordWrite, respectively.

WordRead

Sequential, streaming word-by-word reads.

WordSeek

Seekability for WordRead and WordWrite streams.

WordWrite

Sequential, streaming word-by-word writes.

Functions

check_tables

Utility function to check that the peek word is large enough.

Type Aliases

BE

Alias for BigEndian

LE

Alias for LittleEndian

NE

An Alias for NativeEndian

NativeEndian

A type alias for the native endianness of the target platform.