bittle

Zero-cost bitsets over native Rust types.

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

Usage

Add bittle as a dependency in your Cargo.toml:

[dependencies]
bittle = "0.4.1"

Guide

This crate defines the Bits, BitsMut, and BitsOwned traits which allows for generically interacting bit sets over existing Rust types such as u32, [u32; 4], or &[u32]:

use bittle::Bits;

let array: [u32; 4] = [0, 1, 2, 3];
assert!(array.iter_ones().eq([63, 94, 126, 127]));

let n = 0b10001000_00000000_00000000_00000000u32;
assert!(n.iter_ones().eq([0, 4]));

let array_of_arrays: [[u8; 4]; 2] = [[8, 0, 0, 0], [0, 0, 128, 0]];
assert!(array_of_arrays.iter_ones().eq([4, 48]));

let mut vec: Vec<u32> = vec![0, 1, 2, 3];
assert!(vec.iter_ones().eq([63, 94, 126, 127]));

We provide the set! macro, which is a zero-cost convenience method of constructing primitive forms of bit sets:

use bittle::Bits;

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

let array_of_arrays: [[u8; 4]; 2] = bittle::set![4, 48];
assert!(array_of_arrays.iter_ones().eq([4, 48]));

let n: u32 = bittle::set![0, 4];
assert!(n.iter_ones().eq([0, 4]));

Since a vector is not a primitive bit set, it could instead make use of BitsMut directly:

use bittle::{Bits, BitsMut};

let mut vec: Vec<u32> = vec![0u32; 4];
vec.set_bit(63);
vec.set_bit(94);
vec.set_bit(126);
vec.set_bit(127);
assert!(vec.iter_ones().eq([63, 94, 126, 127]));

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

• Something like is_empty becomes all_zeros - since with bits you're thinking about "ones and zeros".
• Testing if a bit is set is test_bit, or in general adding the *_bit suffix to operations over individual bits.
• Clearing all bits becomes clear_bits, or in general adding the *_bits suffix when operating over all bits.

use bittle::{Bits, BitsMut};

let mut set = [0u16; 2];

set.set_bit(15);
assert!(set.test_bit(15));

set.union_assign(&bittle::set![31, 7]);
assert!(set.test_bit(31) && set.test_bit(7));

set.clear_bit(31);
assert!(!set.test_bit(31));

set.clear_bits();
assert!(set.all_zeros());

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

use bittle::{Bits, BitsMut};

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

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