feat: add bloom filter learning artifacts

Author: jeresoftx

Cargo.toml

@@ -133,6 +133,18 @@ path = "examples/soluciones/hashmap_collision_chain.rs"
 name = "solution_hashmap_cache_remove"
 path = "examples/soluciones/hashmap_cache_remove.rs"
 
+[[example]]
+name = "solution_bloom_filter_cache_guard"
+path = "examples/soluciones/bloom_filter_cache_guard.rs"
+
+[[example]]
+name = "solution_bloom_filter_size_estimate"
+path = "examples/soluciones/bloom_filter_size_estimate.rs"
+
+[[example]]
+name = "solution_bloom_filter_false_positive_probe"
+path = "examples/soluciones/bloom_filter_false_positive_probe.rs"
+
 [[bench]]
 name = "vector_bench"
 path = "benches/vector_bench.rs"
@@ -182,3 +194,8 @@ harness = false
 name = "hashmap_bench"
 path = "benches/hashmap_bench.rs"
 harness = false
+
+[[bench]]
+name = "bloom_filter_bench"
+path = "benches/bloom_filter_bench.rs"
+harness = false

benches/bloom_filter_bench.rs

@@ -0,0 +1,61 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+use std::collections::HashSet;
+use std::hint::black_box;
+use std::time::{Duration, Instant};
+
+const SIZE: usize = 20_000;
+
+fn main() {
+    println!("bloom filter benchmark (manual, std::time::Instant)");
+    println!("size: {SIZE}");
+    println!("insert: {:?}", bench_insert());
+    println!("positive membership: {:?}", bench_positive_membership());
+    println!("negative membership: {:?}", bench_negative_membership());
+    println!("hashset exact membership: {:?}", bench_hashset_membership());
+}
+
+fn bench_insert() -> Duration {
+    let start = Instant::now();
+    let mut filter = BloomFilter::with_estimated_items(SIZE, 0.01).unwrap();
+    for key in 0..SIZE {
+        filter.insert(&black_box(key));
+    }
+    black_box(filter.set_bit_count());
+    start.elapsed()
+}
+
+fn bench_positive_membership() -> Duration {
+    let mut filter = BloomFilter::with_estimated_items(SIZE, 0.01).unwrap();
+    for key in 0..SIZE {
+        filter.insert(&key);
+    }
+
+    let start = Instant::now();
+    for key in 0..SIZE {
+        black_box(filter.might_contain(&key));
+    }
+    start.elapsed()
+}
+
+fn bench_negative_membership() -> Duration {
+    let mut filter = BloomFilter::with_estimated_items(SIZE, 0.01).unwrap();
+    for key in 0..SIZE {
+        filter.insert(&key);
+    }
+
+    let start = Instant::now();
+    for key in SIZE..(SIZE * 2) {
+        black_box(filter.might_contain(&key));
+    }
+    start.elapsed()
+}
+
+fn bench_hashset_membership() -> Duration {
+    let set: HashSet<usize> = (0..SIZE).collect();
+
+    let start = Instant::now();
+    for key in 0..SIZE {
+        black_box(set.contains(&key));
+    }
+    start.elapsed()
+}

diagrams/11-bloom-filter.mmd

@@ -0,0 +1,38 @@
+flowchart TB
+    title["Bloom Filter: pertenencia probabilistica"]
+
+    value["valor: url:/manual/rfc-0001"]
+    h1["hash 1"]
+    h2["hash 2"]
+    h3["hash 3"]
+
+    value --> h1
+    value --> h2
+    value --> h3
+
+    subgraph bits["Arreglo de bits"]
+        b0["0: 0"]
+        b1["1: 1"]
+        b2["2: 0"]
+        b3["3: 1"]
+        b4["4: 0"]
+        b5["5: 1"]
+        b6["6: 0"]
+    end
+
+    h1 --> b1
+    h2 --> b3
+    h3 --> b5
+
+    insert["insert<br/>enciende k bits"]
+    query["might_contain<br/>revisa k bits"]
+    missing["algun bit en 0<br/>definitivamente no esta"]
+    maybe["todos en 1<br/>podria estar"]
+    fp["falso positivo<br/>colision de bits"]
+    nofn["sin falsos negativos<br/>si se inserto, sus bits siguen en 1"]
+
+    value --> insert --> bits
+    bits --> query
+    query --> missing
+    query --> maybe --> fp
+    maybe --> nofn

examples/bloom_filter_advanced.rs

@@ -0,0 +1,21 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let mut filter = BloomFilter::with_estimated_items(1_000, 0.02).unwrap();
+
+    for id in 0..1_000 {
+        filter.insert(&format!("visited:{id}"));
+    }
+
+    let false_positives = (10_000..11_000)
+        .filter(|id| filter.might_contain(&format!("visited:{id}")))
+        .count();
+    let measured_rate = false_positives as f64 / 1_000.0;
+
+    println!("falsos positivos medidos: {false_positives}");
+    println!("tasa medida: {measured_rate:.4}");
+    println!(
+        "tasa estimada por formula: {:.4}",
+        filter.estimated_false_positive_rate()
+    );
+}

examples/bloom_filter_basic.rs

@@ -0,0 +1,15 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let mut filter = BloomFilter::new(128, 3).unwrap();
+
+    filter.insert(&"rust");
+    filter.insert(&"data-structures");
+
+    println!("rust podria estar: {}", filter.might_contain(&"rust"));
+    println!(
+        "python definitivamente no esta: {}",
+        !filter.might_contain(&"python")
+    );
+    println!("bits encendidos: {}", filter.set_bit_count());
+}

examples/bloom_filter_intermediate.rs

@@ -0,0 +1,17 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let mut filter = BloomFilter::with_estimated_items(100, 0.01).unwrap();
+
+    for id in 0..40 {
+        filter.insert(&format!("lesson:{id}"));
+    }
+
+    println!("bits: {}", filter.bit_count());
+    println!("hashes: {}", filter.hash_count());
+    println!("inserciones: {}", filter.inserted_count());
+    println!(
+        "falso positivo estimado: {:.4}",
+        filter.estimated_false_positive_rate()
+    );
+}

examples/bloom_filter_real_case.rs

@@ -0,0 +1,25 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let mut likely_cached = BloomFilter::with_estimated_items(500, 0.01).unwrap();
+
+    for key in [
+        "GET /courses/rust-data-structures",
+        "GET /courses/rust-algorithms",
+        "GET /manual/rfc-0001",
+    ] {
+        likely_cached.insert(&key);
+    }
+
+    for key in [
+        "GET /manual/rfc-0001",
+        "GET /private/admin",
+        "GET /courses/rust-data-structures",
+    ] {
+        if likely_cached.might_contain(&key) {
+            println!("consultar cache o base de datos: {key}");
+        } else {
+            println!("evitar lectura: {key} definitivamente no esta");
+        }
+    }
+}

examples/soluciones/bloom_filter_cache_guard.rs

@@ -0,0 +1,14 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let mut guard = BloomFilter::with_estimated_items(100, 0.01).unwrap();
+
+    for key in ["user:1", "user:2", "course:rust-data-structures"] {
+        guard.insert(&key);
+    }
+
+    assert!(guard.might_contain(&"user:1"));
+    assert!(!guard.might_contain(&"course:missing"));
+
+    println!("guardia de cache listo");
+}

examples/soluciones/bloom_filter_false_positive_probe.rs

@@ -0,0 +1,16 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let mut filter = BloomFilter::with_estimated_items(500, 0.02).unwrap();
+
+    for id in 0..500 {
+        filter.insert(&format!("url:{id}"));
+    }
+
+    let false_positives = (5_000..5_500)
+        .filter(|id| filter.might_contain(&format!("url:{id}")))
+        .count();
+
+    assert!(false_positives < 40);
+    println!("falsos positivos observados: {false_positives}");
+}

examples/soluciones/bloom_filter_size_estimate.rs

@@ -0,0 +1,15 @@
+use rust_data_structures::bloom_filter::BloomFilter;
+
+fn main() {
+    let filter = BloomFilter::with_estimated_items(10_000, 0.01).unwrap();
+
+    assert!(filter.bit_count() >= 95_000);
+    assert!(filter.hash_count() >= 6);
+    assert_eq!(filter.inserted_count(), 0);
+
+    println!(
+        "para 10000 elementos al 1%: {} bits y {} hashes",
+        filter.bit_count(),
+        filter.hash_count()
+    );
+}