readd bitm to apply changes

Author: lucarlig

bitm/Cargo.toml

@@ -0,0 +1,40 @@
+[package]
+name = "bitm"
+version = "0.4.3"
+edition = "2021"
+authors = ["Piotr Beling <[email protected]>"]
+license = "MIT OR Apache-2.0"
+description = "The library for bit and bitmap (bit vector) manipulation."
+documentation = "https://docs.rs/bitm"
+repository = "https://github.com/beling/bsuccinct-rs"
+readme = "README.md"
+include = [ "**/*.rs", "Cargo.toml", "README.md" ]
+categories = [ "algorithms", "data-structures", "science", "encoding" ]
+keywords = [ "bit", "bitmap", "rank", "bitvector", "bitset" ]
+
+[dependencies]
+dyn_size_of = { version=">=0.4.3", path="../dyn_size_of" }
+aligned-vec = { version="0.6", optional=true }  # for construcing cache-aligment bit vectors, which usually speeds up rank and select
+
+[dev-dependencies]
+criterion = "0.5"
+iai-callgrind = "0.10"
+
+[features]
+aligned-vec = ["dep:aligned-vec", "dyn_size_of/aligned-vec"]
+
+
+[[bench]]
+name = "bitvec"
+harness = false
+
+[[bench]]
+name = "rank_select"
+harness = false
+
+[[bench]]
+name = "bitvec-iai"
+harness = false
+
+#[profile.bench]
+#debug = true

bitm/README.md

@@ -0,0 +1,23 @@
+`bitm` is the Rust library by Piotr Beling for bit and bitmap (bit vector) manipulation.
+
+# Example
+
+```rust
+use bitm::{BitAccess, BitVec, Rank, ArrayWithRank101111};
+
+let mut b = Box::<[u64]>::with_zeroed_bits(2048);    // b can store 2048 bits
+assert_eq!(b.get_bit(100), false);  // b is zeroed so bit at index 100 is not set  
+b.set_bit(100);                     // set the bit
+assert_eq!(b.get_bit(100), true);   // now it is set
+assert_eq!(b.get_bits(99, 5), 0b00010); // 5 bits, beginning from index 99, should be 00010
+
+let (r, ones) = ArrayWithRank101111::build(b);
+assert_eq!(ones, 1);        // one bit is set in b
+assert_eq!(r.rank(100), 0); // no ones in the first 100 bits of b
+assert_eq!(r.rank(101), 1); // 1 one in the first 101 bits of b
+assert_eq!(r.rank(999), 1); // 1 one in the first 999 bits of b
+```
+
+# Benchmarks
+The performance of some of the structures included in `bitm` can be tested with the [cseq_benchmark](https://crates.io/crates/cseq_benchmark) crate. Its documentation contains benchmark results.
+

bitm/benches/bitvec-iai.rs

@@ -0,0 +1,62 @@
+use iai_callgrind::{black_box, main, library_benchmark_group, library_benchmark};
+use bitm::BitAccess;
+
+#[library_benchmark]
+#[bench::short(&[0x6A_21_55_79_10_90_32_F3; 2], 10, 30)]
+#[bench::long(&[0x6A_21_55_79_10_90_32_F3; 2], 10, 60)]
+fn get_bits(tab: &[u64], index: usize, v_size: u8) -> u64 {
+    black_box(tab.get_bits(index, v_size))
+}
+
+#[library_benchmark]
+#[bench::short(&[0x6A_21_55_79_10_90_32_F3; 2], 10, 30)]
+#[bench::long(&[0x6A_21_55_79_10_90_32_F3; 2], 10, 60)]
+fn get_bits_unchecked(tab: &[u64], index: usize, v_size: u8) -> u64 {
+    black_box(unsafe{tab.get_bits_unchecked(index, v_size)})
+}
+
+#[library_benchmark]
+#[bench::short(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, 0xaa_aa_aa, 30)]
+#[bench::long(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, 0xaa_aa_aa_aa_aa_aa, 60)]
+fn set_bits(tab: &mut [u64], index: usize, v: u64, v_size: u8) {
+    tab.set_bits(index, v, v_size)
+}
+
+#[library_benchmark]
+#[bench::short(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, 0xaa_aa_aa, 30)]
+#[bench::long(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, 0xaa_aa_aa_aa_aa_aa, 60)]
+fn set_bits_unchecked(tab: &mut [u64], index: usize, v: u64, v_size: u8) {
+    unsafe { tab.set_bits_unchecked(index, v, v_size) }
+}
+
+#[library_benchmark]
+#[bench::zero(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, false)]
+#[bench::one(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, true)]
+fn set_bit_to(tab: &mut [u64], index: usize, value: bool) {
+    tab.set_bit_to(index, value)
+}
+
+#[library_benchmark]
+#[bench::zero(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, false)]
+#[bench::one(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, true)]
+fn set_bit_to_unchecked(tab: &mut [u64], index: usize, value: bool) {
+    unsafe{tab.set_bit_to_unchecked(index, value)}
+}
+
+#[library_benchmark]
+#[bench::short(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, 30)]
+#[bench::long(&mut [0x6A_21_55_79_10_90_32_F3; 2], 10, 60)]
+fn conditionally_change_bits(tab: &mut [u64], index: usize, v_size: u8) -> u64 {
+    black_box(tab.conditionally_change_bits(|v| (v>2).then(|| v-1), index, v_size))
+}
+
+library_benchmark_group!(
+    name = bitvec;
+    benchmarks =
+        get_bits, get_bits_unchecked,
+        set_bits, set_bits_unchecked,
+        set_bit_to, set_bit_to_unchecked,
+        conditionally_change_bits
+);
+
+main!(library_benchmark_groups = bitvec);

bitm/benches/bitvec.rs

@@ -0,0 +1,74 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion, BenchmarkId};
+use bitm::BitAccess;
+
+pub fn get_bits(c: &mut Criterion) {
+    let v = [0x6A_21_55_79_10_90_32_F3; 4];
+
+    c.bench_function("get_bit (checked)", |b| b.iter(|| v.get_bit(black_box(30))));
+    c.bench_function("get_bit (unchecked)", |b| b.iter(|| unsafe{v.get_bit_unchecked(black_box(30))}));
+
+    let mut group = c.benchmark_group("get_bits (checked)");
+    for size in [20, 40, 60].iter() {
+        //group.throughput(Throughput::Bytes(*size as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            b.iter(|| v.get_bits(black_box(30), size))
+        });
+    }
+    group.finish();
+
+    let mut group = c.benchmark_group("get_bits_unchecked");
+    for size in [20, 40, 60].iter() {
+        //group.throughput(Throughput::Bytes(*size as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            b.iter(|| unsafe{ v.get_bits_unchecked(black_box(30), size) })
+        });
+    }
+    group.finish();
+}
+
+pub fn set_bits(c: &mut Criterion) {
+    let mut v = [0x6A_21_55_79_10_90_32_F3; 4];
+
+    c.bench_function("set_bit (checked)", |b| b.iter(|| v.set_bit(black_box(30))));
+    c.bench_function("set_bit (unchecked)", |b| b.iter(|| unsafe{v.set_bit_unchecked(black_box(30))}));
+
+    let mut group = c.benchmark_group("set_bit_to (checked)");
+    for value in [false, true] {
+        group.bench_with_input(BenchmarkId::from_parameter(value), &value, |b, value| {
+            b.iter(|| v.set_bit_to(black_box(30), black_box(*value)))
+        });
+    }
+    group.finish();
+
+    let mut group = c.benchmark_group("set_bit_to (unchecked)");
+    for value in [false, true] {
+        group.bench_with_input(BenchmarkId::from_parameter(value), &value, |b, value| {
+            b.iter(|| unsafe{v.set_bit_to_unchecked(black_box(30), black_box(*value))})
+        });
+    }
+    group.finish();
+
+    c.bench_function("set_bit_to (checked)", |b| b.iter(|| v.set_bit_to(black_box(30), true)));
+    c.bench_function("set_bit_to (unchecked)", |b| b.iter(|| unsafe{v.set_bit_unchecked(black_box(30))}));
+
+    let mut group = c.benchmark_group("set_bits (checked)");
+    for size in [20, 40, 60].iter() {
+        //group.throughput(Throughput::Bytes(*size as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            b.iter(|| v.set_bits(black_box(30), black_box(0), size))
+        });
+    }
+    group.finish();
+
+    let mut group = c.benchmark_group("set_bits_unchecked");
+    for size in [20, 40, 60].iter() {
+        //group.throughput(Throughput::Bytes(*size as u64));
+        group.bench_with_input(BenchmarkId::from_parameter(size), size, |b, &size| {
+            b.iter(|| unsafe{v.set_bits_unchecked(black_box(30), black_box(0), size)})
+        });
+    }
+    group.finish();
+}
+
+criterion_group!(bit_vector, get_bits, set_bits);
+criterion_main!(bit_vector);

bitm/benches/rank_select.rs

@@ -0,0 +1,14 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use bitm::{RankSelect101111, Rank};
+
+pub fn rank(c: &mut Criterion) {
+    let bitmap = vec![0x6A_21_55_79_10_90_32_F3; 16].into_boxed_slice();
+    let r: RankSelect101111 = bitmap.into();
+
+    c.bench_function("rank (checked)", |b| b.iter(|| r.rank(black_box(18*7))));
+    c.bench_function("try_rank", |b| b.iter(|| r.try_rank(black_box(18*7))));
+    c.bench_function("rank_unchecked", |b| b.iter(|| unsafe{r.rank_unchecked(black_box(18*7))}));
+}
+
+criterion_group!(rank_select, rank);
+criterion_main!(rank_select);