## quark

Types for manipulating numeric primitives at the bit level

### 2 stable releases

 1.1.0 Jan 4, 2019 Dec 23, 2018 Jun 30, 2017

#844 in Rust patterns

27KB
500 lines

# `quark`

Types for manipulating numeric primitives at the bit level.

The `quark` crate provides traits for accessing parts of numeric primitives and adds new types to represent numbers using bit counts that aren't included in the standard library.

## Bit Indexing

Accessing a bit or range of bits in a numeric primitive can be awkward and less than readable using shifts and masks:

``````let big: u16 = 0x35;
let small = big >> 2 & 0x1f;
assert_eq!(small, 0xd);
``````

At a glance, it's not easy to parse things like:

• How many bits are contributing to the resulting value and which ones are definitely zero?
• Which bits in the original value are in the result?

Using the `BitIndex` trait, the above example can be written as:

``````use quark::BitIndex;

let big: u16 = 0x35;
let small = big.bits(2..7);
assert_eq!(small, 0xd);
``````

The `BitMask` trait allows for easily generating a bit mask using just the length and apply masks:

``````use quark::BitMask;

let value: u32 = 0x1234_5678;
``````

## Bit Sizes

When implementing a trait on numeric types, sometimes the number of bits of a type will be required. One way around this is adding a `bit_size()` or `bit_length()` method to the trait in order to return a constant for each type. The `BitSize` trait adds a `BIT_SIZE` constant to the numeric types that can be used in implementing traits without needing another method.

## Sign Extension

The `Signs` trait adds methods for checking the sign bit on unsigned primitives (and signed ones) and for sign-extending values an arbitrary number of bits:

``````use quark::Signs;

let unsigned = 0x00ff_ffffu32;
let signed = unsigned.sign_extend(8);
assert_eq!(signed, 0xffff_ffff);
``````

## Why `quark`?

Because our programs are primitives at the very lowest level, types like `i32`, `u8`, and `usize` are like atomic pieces of data. The `quark` crate goes to the next level down, and quarks are at that next level w.r.t. atoms.

Also, I have an affinity for names with a 'Q' because my last name starts with one.