bittle

A library for working with bitsets.

The name bittle comes from bit and little. Small bitsets!

This crate defines the [Bits] and [OwnedBits] traits which allows for generically interacting with and manipulating bit sets over types such as u128, [u32; 4], or even slices like &[u8].

To to these implementations it is possible to use bit-oriented APIs on regular types, such as with arrays and vectors:

use bittle::Bits;

let array: [u32; 4] = bittle::set![4, 63, 71];
assert!(array.iter_ones().eq([4, 63, 71]));
assert!(array.bit_test(63));

let mut vector: Vec<u8> = vec![0, 1, 2, 3];
dbg!(vector.iter_ones().collect::<Vec<_>>());
assert!(vector.iter_ones().eq([8, 17, 24, 25]));

vector.bit_set(20);
assert_eq!(vector, [0, 1, 18, 3]);

Usage

Add bittle as a dependency in your Cargo.toml:

[dependencies]
bittle = "0.3.5"

Guide

Due to how broadly these traits are implemented, we also try and avoid using names which are commonly used in other APIs, instead opting for terminology such as:

• is_empty becomes is_zeros.
• test becomes bit_test.
• set becomes bit_set.
• clear becomes bits_clear.

use std::mem;

use bittle::Bits;

let mut a = 0u64;

assert!(a.is_zeros());

assert!(!a.bit_test(31));
a.bit_set(31);
assert!(a.bit_test(31));
a.bit_clear(31);
assert!(!a.bit_test(31));

Some other interesting operations, such as Bits::join_ones are available, allowing bitsets to act like masks over other iterators:

use bittle::Bits;

let elements = vec![10, 48, 101];
let mut m = 0u128;

m.bit_set(0);
assert!(m.join_ones(&elements).eq([&10]));
m.bit_set(2);
assert!(m.join_ones(&elements).eq([&10, &101]));