Crate halfling

Basic utilities and structures for handling nibbles.

Nibbles

A nibble (sometimes also nybble or nybl) is a 4-bit unit of data, equivalent in size to a single-digit hexadecimal number.

Historically, nibbles were used in early computers to represent small enumerations, e.g. the individual digits of a base-10 number, but today they are largely API details (as opposed to genuinely necessary memory-saving constructs).

halfling’s Nibble is a byte-width struct containing a single nibble, which guarantees that the niche value optimization will apply. (a Nibble has 4 unused bits, and hence 240 such niches are available). They are byte-width due to Rust’s fundamental expectation that types are at byte-aligned, which prevents us from constructing a single type that genuinely consumes only a nibble of memory.

Ordering Nibbles

When representing larger units of data in terms of bytes, we need to agree on the “correct” order of the bytes. The two most-common representations are little-endian (LE) and big-endian (BE), which define the first byte to be the least and most significant byte respectively.

Similarly, a byte can be divided into two Nibble values in two ways, depending on whether the least-significant nibble is first or second. The unit structs Le and Be provide implementations of the Ordering trait for these two orderings, and are used to control the order in which a Nibbles iterator produces values.

Structs

• Be
  The big-endian Nibble Ordering marker.
• Le
  The little-endian Nibble Ordering marker.
• Nibble
  A byte-width nibble, representing a 4-bit unit of data.
• NibbleTryFromIntError
  The error produced if a conversion from an integral type to a Nibble fails.
• Nibbles
  A Nibble iterator over a &[u8] with Ordering defined by O.

Traits

• Ordering
  An ordering for the two Nibble values in a u8.