feat: add Bloom Filter data structure (#65)

Co-authored-by: Alexander Gonzalez <[email protected]>

Cargo.toml

@@ -7,3 +7,4 @@ edition = "2018"
 
 [dependencies]
 paste = "1.0.12"
+bitvec = "1.0.1"

src/data_structures/bloom_filter.rs

@@ -0,0 +1,334 @@
+//! Bloom Filter is a probabilistic data structure designed to determine whether a given element
+//! is a member of a set. The main characteristic of the Bloom Filter is it may give false
+//! positives but never false negatives. In other words, a query returns either "possibly in set"
+//! or "definitely not in set".
+//!
+//! This uses the [BitVec](https://crates.io/crates/bitvec) crate to store the bits.
+//!
+//! Consider looking into [Fnv](https://crates.io/crates/fnv) crate for more efficient hashing.
+
+use bitvec::prelude::*;
+use std::collections::hash_map::DefaultHasher;
+use std::hash::{Hash, Hasher};
+
+/// Simple Bloom Filter implementation with a given size and number of hash functions.
+/// Multiple hash functions are used to reduce the probability of false positives.
+///
+/// Example usage:
+/// ```
+/// use std::collections::hash_map::DefaultHasher;
+/// use std::hash::{Hash, Hasher};
+/// use rust_algorithms::data_structures::BloomFilter;
+///
+/// fn main() {
+///     // Define hash functions
+///     let hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>> = vec![
+///         Box::new(|data| {
+///             let mut hasher = DefaultHasher::new();
+///             data.hash(&mut hasher);
+///             hasher.finish()
+///         }),
+///         Box::new(|data| {
+///             let mut hasher = DefaultHasher::new();
+///             data.hash(&mut hasher);
+///             hasher.finish() ^ 0xFFFFFFFFFFFFFFFF // XOR with a constant for diversity
+///         }),
+///     ];
+///
+///     // Create a new BloomFilter with a size of 100 bits and the hash functions
+///     let mut bloom_filter = BloomFilter::new(100, hash_functions);
+///
+///     // Insert elements into the BloomFilter
+///     bloom_filter.insert(&"apple");
+///     bloom_filter.insert(&"banana");
+///     bloom_filter.insert(&"cherry");
+///
+///     // Check if elements are contained in the BloomFilter
+///     println!("Contains 'apple': {}", bloom_filter.contains(&"apple"));     // Should print true
+///     println!("Contains 'orange': {}", bloom_filter.contains(&"orange"));   // Should print false
+///     println!("Contains 'cherry': {}", bloom_filter.contains(&"cherry"));   // Should print true
+/// }
+/// ```
+
+pub struct BloomFilter {
+    /// Stores bits to indicate whether an element may be in the set
+    bit_array: BitVec,
+    /// Hash functions to use
+    hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>>,
+}
+
+impl BloomFilter {
+    /// Creates a new Bloom Filter with the given size and hash functions
+    pub fn new(size: usize, hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>>) -> Self {
+        BloomFilter {
+            bit_array: bitvec![0; size],
+            hash_functions,
+        }
+    }
+
+    /// Inserts an element into the Bloom Filter
+    /// Hashes the element using each hash function and sets the corresponding bit to true
+    ///
+    /// Time Complexity: O(k) where k is the number of hash functions
+    pub fn insert<T>(&mut self, item: &T)
+    where
+        T: AsRef<[u8]> + Hash,
+    {
+        for hash_function in &self.hash_functions {
+            let hash = Self::hash(item, hash_function);
+            let index = hash % self.bit_array.len() as u64;
+            self.bit_array.set(index as usize, true);
+        }
+    }
+
+    /// Checks if an element may be in the Bloom Filter
+    /// NOTE: `true` implies the element may be in the set, `false` implies the element is not in the set.
+    /// The output is *not* deterministic.
+    ///
+    /// Time Complexity: O(k) where k is the number of hash functions
+    pub fn contains<T>(&self, item: &T) -> bool
+    where
+        T: AsRef<[u8]> + Hash,
+    {
+        for hash_function in &self.hash_functions {
+            let hash = Self::hash(item, hash_function);
+            let index = hash % self.bit_array.len() as u64;
+            if !self.bit_array[index as usize] {
+                return false;
+            }
+        }
+        true
+    }
+
+    /// Hashes an element using the given hash function
+    fn hash<T>(item: &T, hash_function: &Box<dyn Fn(&[u8]) -> u64>) -> u64
+    where
+        T: AsRef<[u8]> + Hash,
+    {
+        let mut hasher = DefaultHasher::new();
+        item.hash(&mut hasher);
+        let hash = hasher.finish();
+        hash_function(&hash.to_be_bytes())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::hash_map::DefaultHasher;
+    use std::hash::{Hash, Hasher};
+
+    #[test]
+    fn test_insert_and_contains() {
+        let hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>> = vec![
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish()
+            }),
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish() ^ 0xFFFFFFFFFFFFFFFF
+            }),
+        ];
+
+        let mut bloom_filter = BloomFilter::new(100, hash_functions);
+
+        assert!(!bloom_filter.contains(&"apple"));
+        assert!(!bloom_filter.contains(&"banana"));
+        assert!(!bloom_filter.contains(&"cherry"));
+
+        bloom_filter.insert(&"apple");
+        bloom_filter.insert(&"banana");
+        bloom_filter.insert(&"cherry");
+
+        assert!(bloom_filter.contains(&"apple"));
+        assert!(bloom_filter.contains(&"banana"));
+        assert!(bloom_filter.contains(&"cherry"));
+
+        // Check that false positives are within an acceptable range
+        assert!(!bloom_filter.contains(&"orange"));
+        assert!(!bloom_filter.contains(&"grape"));
+        assert!(!bloom_filter.contains(&"kiwi"));
+    }
+
+    #[test]
+    fn test_false_positive_probability() {
+        // Test the false positive probability by inserting a known set of elements
+        // and checking for false positives with additional elements
+
+        let hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>> = vec![
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish()
+            }),
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish() ^ 0xFFFFFFFFFFFFFFFF
+            }),
+        ];
+
+        let mut bloom_filter = BloomFilter::new(100, hash_functions);
+
+        // Insert known elements
+        let known_elements = vec!["apple", "banana", "cherry"];
+        for element in &known_elements {
+            bloom_filter.insert(element);
+        }
+
+        // Test false positives with additional elements
+        let false_positive_elements = vec!["orange", "grape", "kiwi"];
+        for element in &false_positive_elements {
+            assert!(
+                !bloom_filter.contains(element),
+                "False positive for: {}",
+                element
+            );
+        }
+    }
+
+    #[test]
+    fn test_hash_function_diversity() {
+        // Test that hash functions produce diverse results for different elements
+
+        let hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>> = vec![
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish()
+            }),
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish() ^ 0xFFFFFFFFFFFFFFFF
+            }),
+        ];
+
+        let bloom_filter = BloomFilter::new(100, hash_functions);
+
+        let element1 = "apple";
+        let element2 = "banana";
+
+        let hash1 = BloomFilter::hash(&element1, &bloom_filter.hash_functions[0]);
+        let hash2 = BloomFilter::hash(&element2, &bloom_filter.hash_functions[0]);
+
+        assert_ne!(
+            hash1, hash2,
+            "Hash function 1 produces the same hash for different elements"
+        );
+
+        let hash1 = BloomFilter::hash(&element1, &bloom_filter.hash_functions[1]);
+        let hash2 = BloomFilter::hash(&element2, &bloom_filter.hash_functions[1]);
+
+        assert_ne!(
+            hash1, hash2,
+            "Hash function 2 produces the same hash for different elements"
+        );
+    }
+
+    #[test]
+    fn test_hash_function_consistency() {
+        // Test that hash functions produce consistent results for the same element
+
+        let hash_functions: Vec<Box<dyn Fn(&[u8]) -> u64>> = vec![
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish()
+            }),
+            Box::new(|data| {
+                let mut hasher = DefaultHasher::new();
+                data.hash(&mut hasher);
+                hasher.finish() ^ 0xFFFFFFFFFFFFFFFF
+            }),
+        ];
+
+        let bloom_filter = BloomFilter::new(100, hash_functions);
+
+        let element = "apple";
+
+        let hash1 = BloomFilter::hash(&element, &bloom_filter.hash_functions[0]);
+        let hash2 = BloomFilter::hash(&element, &bloom_filter.hash_functions[0]);
+
+        assert_eq!(
+            hash1, hash2,
+            "Hash function 1 produces different hashes for the same element"
+        );
+
+        let hash1 = BloomFilter::hash(&element, &bloom_filter.hash_functions[1]);
+        let hash2 = BloomFilter::hash(&element, &bloom_filter.hash_functions[1]);
+
+        assert_eq!(
+            hash1, hash2,
+            "Hash function 2 produces different hashes for the same element"
+        );
+    }
+
+    /// more extensive test and contains test
+    #[test]
+    fn test_bloom_filter_extended() {
+        /// Get a vector of hash functions (since they are closures, we can't clone them)
+        fn get_hash_functions() -> Vec<Box<dyn Fn(&[u8]) -> u64>> {
+            vec![
+                Box::new(|data| {
+                    let mut hasher = DefaultHasher::new();
+                    data.hash(&mut hasher);
+                    hasher.finish()
+                }),
+                Box::new(|data| {
+                    let mut hasher = DefaultHasher::new();
+                    data.hash(&mut hasher);
+                    hasher.finish() ^ 0xFFFFFFFFFFFFFFFF
+                }),
+            ]
+        }
+
+        let mut bloom_filter = BloomFilter::new(100, get_hash_functions());
+
+        // Ensure the filter is initially empty
+        assert!(!bloom_filter.contains(&"apple"));
+        assert!(!bloom_filter.contains(&"banana"));
+        assert!(!bloom_filter.contains(&"cherry"));
+
+        // Insert items into the Bloom filter
+        bloom_filter.insert(&"apple");
+        bloom_filter.insert(&"banana");
+        bloom_filter.insert(&"cherry");
+
+        // Check for false positives (items that were not inserted)
+        assert!(!bloom_filter.contains(&"orange"));
+        assert!(!bloom_filter.contains(&"grape"));
+        assert!(!bloom_filter.contains(&"kiwi"));
+
+        // Check for false negatives (items that were inserted)
+        assert!(bloom_filter.contains(&"apple"));
+        assert!(bloom_filter.contains(&"banana"));
+        assert!(bloom_filter.contains(&"cherry"));
+
+        // Create a new Bloom filter with a larger capacity
+        let mut bloom_filter_large = BloomFilter::new(100, get_hash_functions());
+
+        // Insert items into the larger Bloom filter
+        bloom_filter_large.insert(&"orange");
+        bloom_filter_large.insert(&"grape");
+        bloom_filter_large.insert(&"kiwi");
+
+        // Check for false positives in the larger filter
+        assert!(bloom_filter_large.contains(&"orange"));
+        assert!(bloom_filter_large.contains(&"grape"));
+        assert!(bloom_filter_large.contains(&"kiwi"));
+
+        // Check for false negatives in the larger filter
+        assert!(!bloom_filter_large.contains(&"apple"));
+        assert!(!bloom_filter_large.contains(&"banana"));
+        assert!(!bloom_filter_large.contains(&"cherry"));
+
+        // Check the accuracy of the original Bloom filter with new items
+        assert!(!bloom_filter.contains(&"orange"));
+        assert!(!bloom_filter.contains(&"grape"));
+        assert!(!bloom_filter.contains(&"kiwi"));
+    }
+}

src/data_structures/mod.rs

@@ -1,6 +1,7 @@
 mod avl_tree;
 mod b_tree;
 mod binary_search_tree;
+mod bloom_filter;
 mod fenwick_tree;
 mod graph;
 mod heap;
@@ -13,6 +14,7 @@ mod stack_using_singly_linked_list;
 mod trie;
 mod union_find;
 
+pub use self::bloom_filter::BloomFilter;
 pub use self::heap::MaxHeap;
 pub use self::heap::MinHeap;
 pub use self::linked_list::LinkedList;