Struct BitMap

Source

pub struct BitMap<const N: usize> { /* private fields */ }

Expand description

A historical bitmap that maintains one actual bitmap plus diffs for history and batching.

Commit numbers must be strictly monotonically increasing and < u64::MAX.

Implementations§

Source §

impl<const N: usize> BitMap<N>

Source

pub fn new() -> Self

Create a new empty historical bitmap.

Source

pub fn new_with_pruned_chunks(pruned_chunks: usize) -> Result<Self, Error>

Create a new historical bitmap with the given number of pruned chunks.

Source

pub fn start_batch(&mut self) -> BatchGuard<'_, N>

Start a new batch for making mutations.

The returned BatchGuard must be either committed or dropped. All mutations are applied to the guard’s diff layer and do not affect the current bitmap until commit.

§Examples

let mut bitmap: BitMap<4> = BitMap::new();

let mut batch = bitmap.start_batch();
batch.push(true);
batch.push(false);
batch.commit(1).unwrap();

assert_eq!(bitmap.len(), 2);

§Panics

Panics if a batch is already active.

Source

pub fn with_batch<F>(&mut self, commit_number: u64, f: F) -> Result<(), Error>
where F: FnOnce(&mut BatchGuard<'_, N>),

Execute a closure with a batch and commit it at the given commit number.

§Errors

Returns Error::NonMonotonicCommit if the commit number is not greater than the previous commit.

Returns Error::ReservedCommitNumber if the commit number is u64::MAX.

§Panics

Panics if a batch is already active.

Source

pub fn get_at_commit(&self, commit_number: u64) -> Option<Prunable<N>>

Get the bitmap state as it existed at a specific commit.

Returns None if the commit does not exist or if commit_number is u64::MAX (which is reserved and cannot be used as a commit number).

This reconstructs the historical state by applying reverse diffs backward from the current state. Each commit’s reverse diff describes the state before that commit, so we “undo” commits one by one until we reach the target.

§Examples

let mut bitmap: BitMap<4> = BitMap::new();

bitmap.with_batch(1, |batch| {
    batch.push(true);
    batch.push(false);
}).unwrap();

bitmap.with_batch(2, |batch| {
    batch.set_bit(0, false);
    batch.push(true);
}).unwrap();

// Get state as it was at commit 1
let state_at_1 = bitmap.get_at_commit(1).unwrap();
assert_eq!(state_at_1.len(), 2);
assert!(state_at_1.get_bit(0));
assert!(!state_at_1.get_bit(1));

// Current state is different
assert_eq!(bitmap.len(), 3);
assert!(!bitmap.get_bit(0));