2 stable releases
1.1.0 | Jan 4, 2019 |
---|---|
1.0.0 | Dec 23, 2018 |
0.0.0 |
|
#1429 in Rust patterns
37 downloads per month
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);
Bit Masks
The BitMask
trait allows for easily generating a bit mask using just the
length and apply masks:
use quark::BitMask;
let mask = u32::mask(8);
assert_eq!(mask, 0xff);
let value: u32 = 0x1234_5678;
assert_eq!(value.mask_to(16), 0x5678);
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.