Merge pull request #8 from yourbasic/tip

Tip

Author: korthaj

example_test.go

@@ -3,7 +3,6 @@ package bloom_test
 import (
 	"fmt"
 	"github.com/yourbasic/bloom"
-	"math/rand"
 	"strconv"
 )
 
@@ -26,30 +25,6 @@ func Example_basics() {
 	// Output: https://rascal.com seems to be shady.
 }
 
-// Estimate the number of false positives.
-func Example_falsePositives() {
-	// Create a Bloom filter with room for n elements
-	// at a false-positives rate less than 1/p.
-	n, p := 10000, 100
-	filter := bloom.New(n, p)
-
-	// Add n random strings.
-	for i := 0; i < n; i++ {
-		filter.Add(strconv.Itoa(rand.Int()))
-	}
-
-	// Do n random lookups and count the (mostly accidental) hits.
-	// It shouldn't be much more than n/p, and hopefully less.
-	count := 0
-	for i := 0; i < n; i++ {
-		if filter.Test(strconv.Itoa(rand.Int())) {
-			count++
-		}
-	}
-	fmt.Println(count, "mistakes were made.")
-	// Output: 26 mistakes were made.
-}
-
 // Compute the union of two filters.
 func ExampleFilter_Union() {
 	// Create two Bloom filters, each with room for 1000 elements

filter.go

@@ -9,10 +9,18 @@
 // a member”. Only false positives can occur: an element that has been added
 // to the filter will always be identified as ”likely member”.
 //
+// The probabilities of different outcomes of a membership test at
+// a false-positives rate of 1/100 are:
+//
+//	Test(s)                 true     false
+//	--------------------------------------
+//	s has been added        1        0
+//	s has not been added    0.01     0.99
+//
 // Elements can be added, but not removed. With more elements in the filter,
 // the probability of false positives increases.
 //
-// Implementation
+// Performance
 //
 // A  full filter with a false-positives rate of 1/p uses roughly
 // 0.26ln(p) bytes per element and performs ⌈1.4ln(p)⌉ bit array lookups
@@ -30,11 +38,22 @@
 //	  512      1.6       9
 //	 1024      1.8      10
 //
-// This implementation is not intended for cryptographic use.
 // Each membership test makes a single call to a 128-bit hash function.
 // This improves speed without increasing the false-positives rate
 // as shown by Kirsch and Mitzenmacher.
 //
+// Limitations
+//
+// This implementation is not intended for cryptographic use.
+//
+// The internal data representation is different for big-endian
+// and little-endian machines.
+//
+// Typical use case
+//
+// The Basics example contains a typcial use case:
+// a blacklist of shady websites.
+//
 package bloom
 
 import (