Merge pull request kodecocodes#62 from Jamil/master

Add Bloom Filter Implementation & Description

Author: hollance

Bloom Filter/BloomFilter.swift

@@ -0,0 +1,58 @@
+import Foundation
+
+public class BloomFilter<T> {
+    private(set) private var arr: [Bool]
+    private(set) private var hashFunctions: [T -> Int]
+    
+    public init(size: Int = 1024, hashFunctions: [T -> Int]) {
+        self.arr = Array<Bool>(count: size, repeatedValue: false)
+        self.hashFunctions = hashFunctions
+    }
+    
+    private func computeHashes(value: T) -> [Int] {
+        return hashFunctions.map() { hashFunc in
+            abs(hashFunc(value) % self.arr.count)
+        }
+    }
+    
+    public func insert(toInsert: T) {
+        let hashValues: [Int] = self.computeHashes(toInsert)
+        
+        for hashValue in hashValues {
+            self.arr[hashValue] = true
+        }
+    }
+    
+    public func insert(values: [T]) {
+        for value in values {
+            self.insert(value)
+        }
+    }
+    
+    public func query(value: T) -> Bool {
+        let hashValues = self.computeHashes(value)
+        
+        // Map hashes to indices in the Bloom filter
+        let results = hashValues.map() { hashValue in
+            self.arr[hashValue]
+        }
+        
+        // All values must be 'true' for the query to return true
+
+        // This does NOT imply that the value is in the Bloom filter,
+        // only that it may be. If the query returns false, however,
+        // you can be certain that the value was not added.
+
+        let exists = results.reduce(true, combine: { $0 && $1 })
+        
+        return exists
+    }
+    
+    public func isEmpty() -> Bool {
+        // Reduce list; as soon as the reduction hits a 'true' value, the && condition will fail
+        return arr.reduce(true) { prev, next in
+            prev && !next
+        }
+    }
+    
+}

Bloom Filter/BloomFilterTests/BloomFilterTests.swift

@@ -0,0 +1,78 @@
+import XCTest
+import BloomFilter
+
+/* Two hash functions, adapted from
+    http://www.cse.yorku.ca/~oz/hash.html */
+
+
+func djb2(x: String) -> Int {
+    var hash = 5381
+    
+    for char in x.characters {
+        hash = ((hash << 5) &+ hash) &+ char.hashValue
+    }
+    
+    return Int(hash)
+}
+
+func sdbm(x: String) -> Int {
+    var hash = 0
+    
+    for char in x.characters {
+        hash = char.hashValue &+ (hash << 6) &+ (hash << 16) &- hash;
+    }
+    
+    return Int(hash)
+}
+
+
+class BloomFilterTests: XCTestCase {
+    
+    func testSingleHashFunction() {
+        let bloom = BloomFilter<String>(hashFunctions: [djb2])
+        
+        bloom.insert("Hello world!")
+        
+        let result_good = bloom.query("Hello world!")
+        let result_bad = bloom.query("Hello world")
+        
+        XCTAssertTrue(result_good)
+        XCTAssertFalse(result_bad)
+    }
+    
+    func testEmptyFilter() {
+        let bloom = BloomFilter<String>(hashFunctions: [djb2])
+        
+        let empty = bloom.isEmpty()
+        
+        XCTAssertTrue(empty)
+    }
+    
+    func testMultipleHashFunctions() {
+        let bloom = BloomFilter<String>(hashFunctions: [djb2, sdbm])
+        
+        bloom.insert("Hello world!")
+        
+        let result_good = bloom.query("Hello world!")
+        let result_bad = bloom.query("Hello world")
+        
+        XCTAssertTrue(result_good)
+        XCTAssertFalse(result_bad)
+    }
+    
+    func testFalsePositive() {
+        let bloom = BloomFilter<String>(size: 5, hashFunctions: [djb2, sdbm])
+        
+        bloom.insert(["hello", "elloh", "llohe", "lohel", "ohell"])
+        
+        print("Inserted")
+        
+        let query = bloom.query("This wasn't inserted!")
+        
+        // This is true even though we did not insert the value in the Bloom filter;
+        // the Bloom filter is capable of producing false positives but NOT 
+        // false negatives.
+        
+        XCTAssertTrue(query)
+    }
+}

Bloom Filter/README.markdown

@@ -0,0 +1,58 @@
+# Bloom Filter
+
+## Introduction
+
+A Bloom Filter is a space-efficient data structure to check for an element in a set, that guarantees that there are no false negatives on queries. In other words, a query to a Bloom filter either returns "false", meaning the element is definitely not in the set, or "true", meaning that the element could be in the set. At first, this may not seem too useful. However, it's important in applications like cache filtering and data synchronization.
+
+An advantage of the Bloom Filter over a hash table is that the former maintains constant memory usage and constant-time insert and search. For a large number of elements in a set, the performance difference between a hash table and a Bloom Filter is significant, and it is a viable option if you do not need the guarantee of no false positives.
+
+## Implementation
+
+A Bloom Filter is essentially a fixed-length bit vector. To insert an element in the filter, it is hashed with *m* different hash functions, which map to indices in the array. The bits at these indices are set to `1`, or `true`, when an element is inserted.
+
+Querying, similarly, is accomplished by hashing the expected value, and checking to see if all of the bits at the indices are `true`. If even one of the bits is not `true`, the element could not have been inserted - and the query returns `false`. If all the bits are `true`, the query returns likewise. If there are "collisions", the query may erroneously return `true` even though the element was not inserted - bringing about the issue with false positives mentioned earlier.
+
+Deletion is not possible with a Bloom Filter, since any one bit might have been set by multiple elements inserted. Once you add an element, it's in there for good.
+
+## The Code
+
+The code is extremely straightforward, as you can imagine. The internal bit array is set to a fixed length on initialization, which cannot be mutated once it is initialized. Several hash functions should be specified at initialization, which will depend on the types you're using. You can see some examples in the tests - the djb2 and sdbm hash functions for strings.
+
+```swift
+public init(size: Int = 1024, hashFunctions: [T -> Int]) {
+    self.arr = Array<Bool>(count: size, repeatedValue: false)
+    self.hashFunctions = hashFunctions
+}
+```
+
+Insertion just flips the required bits to `true`:
+
+```swift
+public func insert(toInsert: T) {
+    let hashValues: [Int] = self.computeHashes(toInsert)
+
+    for hashValue in hashValues {
+        self.arr[hashValue] = true
+    }
+}
+```
+
+And querying checks to make sure the bits at the hashed values are `true`:
+
+```swift
+public func query(value: T) -> Bool {
+    let hashValues = self.computeHashes(value)
+
+    let results = hashValues.map() { hashValue in
+        self.arr[hashValue]
+    }
+
+    let exists = results.reduce(true, combine: { $0 && $1 })
+
+    return exists
+}
+```
+
+If you're coming from another imperative language, you might notice the unusual syntax in the `exists` constant assignment. Swift makes use of functional paradigms when it makes code more consise and readable, and in this case, `reduce` is a much more consise way to check if all the required bits are `true` than a `for` loop. 
+
+*Written for Swift Algorithm Club by Jamil Dhanani*

README.markdown

@@ -154,7 +154,7 @@ Most of the time using just the built-in `Array`, `Dictionary`, and `Set` types
 
 ### Sets
 
-- Bloom Filter
+- [Bloom Filter](Bloom Filter/). A constant-memory data structure that probabilistically tests whether an element is in a set.
 - [Hash Set](Hash Set/). A set implemented using a hash table.
 - Multiset
 - Ordered Set