Tweak text and code style

Add examples to description
Add playground
Add test project

Bloom Filter/BloomFilter.playground/Contents.swift

@@ -0,0 +1,86 @@
+//: Playground - noun: a place where people can play
+
+public class BloomFilter<T> {
+  private var array: [Bool]
+  private var hashFunctions: [T -> Int]
+
+  public init(size: Int = 1024, hashFunctions: [T -> Int]) {
+    self.array = .init(count: size, repeatedValue: false)
+    self.hashFunctions = hashFunctions
+  }
+
+  private func computeHashes(value: T) -> [Int] {
+    return hashFunctions.map() { hashFunc in abs(hashFunc(value) % array.count) }
+  }
+
+  public func insert(element: T) {
+    for hashValue in computeHashes(element) {
+      array[hashValue] = true
+    }
+  }
+
+  public func insert(values: [T]) {
+    for value in values {
+      insert(value)
+    }
+  }
+
+  public func query(value: T) -> Bool {
+    let hashValues = computeHashes(value)
+
+    // Map hashes to indices in the Bloom Filter
+    let results = hashValues.map() { hashValue in array[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 {
+    // As soon as the reduction hits a 'true' value, the && condition will fail.
+    return array.reduce(true) { prev, next in prev && !next }
+  }
+}
+
+
+
+/* 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)
+}
+
+
+
+/* A simple test */
+
+let bloom = BloomFilter<String>(size: 17, hashFunctions: [djb2, sdbm])
+
+bloom.insert("Hello world!")
+print(bloom.array)
+
+bloom.query("Hello world!")    // true
+bloom.query("Hello WORLD")     // false
+
+bloom.insert("Bloom Filterz")
+print(bloom.array)
+
+bloom.query("Bloom Filterz")   // true
+bloom.query("Hello WORLD")     // true

Bloom Filter/BloomFilter.playground/contents.xcplayground

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<playground version='5.0' target-platform='osx'>
+    <timeline fileName='timeline.xctimeline'/>
+</playground>

Bloom Filter/BloomFilter.playground/timeline.xctimeline

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Timeline
+   version = "3.0">
+   <TimelineItems>
+   </TimelineItems>
+</Timeline>

Bloom Filter/BloomFilter.swift

@@ -1,58 +1,46 @@
-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 var array: [Bool]
+  private var hashFunctions: [T -> Int]
+
+  public init(size: Int = 1024, hashFunctions: [T -> Int]) {
+    self.array = .init(count: size, repeatedValue: false)
+    self.hashFunctions = hashFunctions
+  }
+
+  private func computeHashes(value: T) -> [Int] {
+    return hashFunctions.map() { hashFunc in abs(hashFunc(value) % array.count) }
+  }
+
+  public func insert(element: T) {
+    for hashValue in computeHashes(element) {
+      array[hashValue] = true
     }
-    
-    private func computeHashes(value: T) -> [Int] {
-        return hashFunctions.map() { hashFunc in
-            abs(hashFunc(value) % self.arr.count)
-        }
+  }
+
+  public func insert(values: [T]) {
+    for value in values {
+      insert(value)
     }
+  }
+
+  public func query(value: T) -> Bool {
+    let hashValues = computeHashes(value)
 
-    public func insert(toInsert: T) {
-        let hashValues: [Int] = self.computeHashes(toInsert)
-
-        for hashValue in hashValues {
-            self.arr[hashValue] = true
-        }
-    }
+    // Map hashes to indices in the Bloom Filter
+    let results = hashValues.map() { hashValue in array[hashValue] }
 
-    public func insert(values: [T]) {
-        for value in values {
-            self.insert(value)
-        }
-    }
+    // All values must be 'true' for the query to return true
 
-    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
-        }
-    }
+    // 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 {
+    // As soon as the reduction hits a 'true' value, the && condition will fail.
+    return array.reduce(true) { prev, next in prev && !next }
+  }
+}

Bloom Filter/README.markdown

@@ -2,57 +2,100 @@
 
 ## 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.
+A Bloom Filter is a space-efficient data structure that tells you whether or not an element is present in a set.
 
-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.
+This is a probabilistic data structure: a query to a Bloom filter either returns `false`, meaning the element is definitely not in the set, or `true`, meaning that the element *might* be in the set.
 
-## Implementation
+There is a small probability of false positives, where the element isn't actually in the set even though the query returned `true`. But there will never any false negatives: you're guaranteed that if the query returns `false`, then the element really isn't in the set.
 
-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.
+So a Bloom Filter tells you, "definitely not" or "probably yes".
 
-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.
+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 sets with a large number of elements, 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.
+
+> **Note:** Unlike a hash table, the Bloom Filter does not store the actual objects. It just remembers what objects you’ve seen (with a degree of uncertainty) and which ones you haven’t.
+
+## How it works
+
+A Bloom Filter is essentially a fixed-length [bit vector](../Bit Set/), an array of bits. When we insert objects, we set some of these bits to `1`, and when we query for objects we check if certain bits are `0` or `1`. Both operations use hash functions.
+
+To insert an element in the filter, the element is hashed with several different hash functions. Each hash function returns a value that we map to an index in the array. We set the bits at these indices to `1` or true.
+
+For example, let's say this is our array of bits. We have 17 bits and initially they are all `0` or false:
+
+	[ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
+
+Now we want to insert the string `"Hello world!"` into the Bloom Filter. We apply two hash functions to this string. The first one gives the value 1999532104120917762. We map this hash value to an index into our array by taking the modulo of the array length: `1999532104120917762 % 17 = 4`. This means we set the bit at index 4 to `1` or true:
+
+	[ 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
+
+Then we hash the original string again but this time with a different hash function. It gives the hash value 9211818684948223801. Modulo 17 that is 12, and we set the bit at index 12 to `1` as well:
+
+	[ 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0 ]
+
+These two bits are enough to tell the Bloom Filter that it now contains the string `"Hello world!"`.
+
+Querying, similarly, is accomplished by first hashing the expected value, which gives several array indices, and then checking to see if all of the bits at those 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.
+
+For example, if we query for the string `"Hello WORLD"`, then the first hash function returns 5383892684077141175, which modulo 17 is 12. That bit is `1`. But the second hash function gives 5625257205398334446, which maps to array index 9. That bit is `0`. This means the string `"Hello WORLD"` is not in the filter and the query returns `false`.
+
+The fact that the first hash function mapped to a `1` bit is a coincidence (it has nothing to do with the fact that both strings start with `"Hello "`). Too many such coincidences can lead to "collisions". 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.
+
+Let's say we insert some other element, `"Bloom Filterz"`, which sets bits 7 and 9. Now the array looks like this:
+
+	[ 0, 0, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 1, 0, 0, 0, 0 ]
+
+If you query for `"Hello WORLD"` again, the filter sees that bit 12 is true and bit 9 is now true as well. It reports that `"Hello WORLD"` is indeed present in the set, even though it isn't... because we never inserted that particular string. It's a false positive. This example shows why a Bloom Filter will never say, "definitely yes", only "probably yes".
+
+You can fix such issues by using an array with more bits and using additional hash functions. Of course, the more hash functions you use the slower the Bloom Filter will be. So you have to strike a balance.
 
 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
+Performance of a Bloom Filter is **O(k)** where **k** is the number of hashing functions.
+
+## 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.
+The code is quite straightforward. The internal bit array is set to a fixed length on initialization, which cannot be mutated once it is initialized. 
 
 ```swift
 public init(size: Int = 1024, hashFunctions: [T -> Int]) {
-    self.arr = Array<Bool>(count: size, repeatedValue: false)
-    self.hashFunctions = hashFunctions
+  self.array = .init(count: size, repeatedValue: false)
+  self.hashFunctions = hashFunctions
 }
 ```
 
+Several hash functions should be specified at initialization. Which hash functions you use will depend on the datatypes of the elements you'll be adding to the set. You can see some examples in the playground and the tests -- the `djb2` and `sdbm` hash functions for strings.
+
 Insertion just flips the required bits to `true`:
 
 ```swift
-public func insert(toInsert: T) {
-    let hashValues: [Int] = self.computeHashes(toInsert)
+public func insert(element: T) {
+  for hashValue in computeHashes(element) {
+    array[hashValue] = true
+  }
+}
+```
 
-    for hashValue in hashValues {
-        self.arr[hashValue] = true
-    }
+This uses the `computeHashes()` function, which loops through the specified `hashFunctions` and returns an array of indices:
+
+```swift
+private func computeHashes(value: T) -> [Int] {
+  return hashFunctions.map() { hashFunc in abs(hashFunc(value) % array.count) }
 }
 ```
 
 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
+  let hashValues = computeHashes(value)
+  let results = hashValues.map() { hashValue in array[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. 
+If you're coming from another imperative language, you might notice the unusual syntax in the `exists` 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*
+*Written for Swift Algorithm Club by Jamil Dhanani. Edited by Matthijs Hollemans.*

Bloom Filter/BloomFilterTests/BloomFilterTests.swift → Bloom Filter/Tests/BloomFilterTests.swift

@@ -1,10 +1,8 @@
 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
 

Bloom Filter/Tests/Info.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundlePackageType</key>
+	<string>BNDL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0</string>
+	<key>CFBundleSignature</key>
+	<string>????</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+</dict>
+</plist>