binvec

binvec provides a fixed-size, stack-allocated bit vector implemented with const generics. It packs boolean values densely into bytes so you can store large sets of flags without the overhead of bool slices or heap allocations.

Highlights

Packs L boolean values into (L + 7) / 8 bytes with zero heap usage.
Const-generic type Binvec<L, N> gives compile-time guarantees about bit length.
Ergonomic binvec! macro computes the minimal byte length for you.
Constant-time indexing with get/set and checked or unchecked access variants.
Methods for bulk operations such as fill, count_ones, count_zeros, and predicates for all-one/zero checks.
Iterator support via BinvecIter for integration with the iterator ecosystem.

Installation

Add the crate to your Cargo.toml:

[dependencies]
binvec = "0.1"

ℹ️ The crate currently uses only core APIs internally, but it is exported as a normal std crate. No additional features or dependencies are required.

Quick Start

use binvec::*;

// Create a 12-bit binvec filled with zeros
let mut flags = binvec!(12, false);

// Flip a couple of bits
flags.set(3, true).unwrap();
flags.set(7, true).unwrap();

assert_eq!(flags.get(3), Some(true));
assert_eq!(flags.count_ones(), 2);
assert!(!flags.is_all_zero());

The binvec! macro is the recommended constructor. It expands to a const instantiation of Binvec<L, N> where N is (L + 7) >> 3, ensuring the backing byte array is the minimal size required to hold the requested bit length.

API Overview

Binvec::<L, N>: main container type. Use the macro unless you need to specify both const parameters manually.
get / set: checked accessors that return Option<bool> or Result<(), IndexOutOfBounds>.
get_unchecked / set_unchecked: unchecked versions for hot paths where you can guarantee the index is in range (calling these with an out-of-bounds index is UB).
fill, count_ones, count_zeros, is_all_one, is_all_zero: helpers for bulk inspection.
iter: yields bool values and integrates with for loops and iterator adapters.
BinvecIter: explicit iterator type if you need to hold the iterator value.

The crate also exposes the error::IndexOutOfBounds error type so you can handle checked writes ergonomically:

use binvec::*;

let mut bits = binvec!(8, false);
match bits.set(32, true) {
    Ok(()) => { /* success */ }
    Err(e) => eprintln!("write failed: {e}"),
}

Safety & Performance Notes