Tip

README.md

@@ -1,6 +1,10 @@
 # Your basic bit
 
-Golang bit array implementation with bonus bit-twiddling functions
+### Golang set data structure with bonus bit-twiddling functions
+
+A bit array, or bit set, is an efficient set data structure.
+It consists of an array that compactly stores bits and it uses
+bit-level parallelism to perform operations quickly. 
 
 ![Venn diagram](venn.png)
 
@@ -22,7 +26,7 @@ There is an online reference for the package at
 * Version numbers adhere to [semantic versioning][sv].
 
 The only accepted reason to modify the API of this package is to
-handle bug fixes that can't be resolved in any other reasonable way.
+handle issues that can't be resolved in any other reasonable way.
 
 Stefan Nilsson – [korthaj](https://github.com/korthaj)
 

example_test.go

@@ -11,7 +11,8 @@ func Example_basics(){
  // Add all elements in the range [0, 100) to the empty set.
  A := new(bit.Set).AddRange(0, 100) //{0..99}
 
- // Create a new set with the elements 0 and 200, and then add [50, 150).
+ // Create a new set containing the two elements 0 and 200,
+ // and then add all elements in the range [50, 150) to the set.
  B := bit.New(0, 200).AddRange(50, 150) //{0 50..149 200}
 
  // Compute the symmetric difference A △ B.
@@ -28,7 +29,7 @@ func Example_basics(){
 }
 
 // Create the set of all primes less than n in O(n log log n) time.
-// Try it with n equal to a few hundred millions and be pleasantly surprised.
+// Try the code with n equal to a few hundred millions and be pleasantly surprised.
 func Example_eratosthenes(){
  // Sieve of Eratosthenes
  const n = 50

example_union_test.go

@@ -10,11 +10,11 @@ func Union(s ...*bit.Set) *bit.Set{
  // Optimization: allocate initital set with adequate capacity.
  max := -1
  for _, x := range s{
- if x.Size() > 0 && x.Max() > max{// Max is undefined for the empty set.
+ if x.Size() > 0 && x.Max() > max{// Max is not defined for the empty set.
  max = x.Max()
  }
  }
- res := bit.New(max) // A negative number is not included.
+ res := bit.New(max) // A negative number will not be included in the set.
 
  for _, x := range s{
  res.SetOr(res, x) // Reuses memory.

set.go

@@ -1,18 +1,20 @@
-// Package bit provides a bit array implementation and some utility bit functions.
+// Package bit provides a bit array implementation
+// and some utility bit functions.
 //
 // Bit functions
 //
-// The functions in this package use bitwise operations instead of
-// looping over individual bits. This gives a considerable speedup,
-// as all bits within a 64-bit word are processed in parallel.
+// The bit functions count leading and trailing zero bits
+// and the number of non-zero bits in a 64-bit word.
+// The functions use bitwise operations instead of looping
+// over individual bits. This gives a considerable speedup,
+// as all bits within the word are processed in parallel.
 //
 // Bit set
 //
-// A bit set allows small arrays of bits to be stored and manipulated
-// in the register set without further memory accesses.
-// Because it exploits bit-level parallelism, limits memory access,
-// and efficiently uses the data cache, a bit set often outperforms other
-// data structures on practical data sets.
+// A bit array, or bit set, is an efficient set data structure
+// that consists of an array of 64-bit words. Because it uses
+// bit-level parallelism, limits memory access, and efficiently uses
+// the data cache, a bit set often outperforms other data structures.
 //
 package bit
 
@@ -65,7 +67,7 @@ func New(n ...int) *Set{
  return s
 }
 
-// Contains tells if n is an element of this set.
+// Contains tells if n is an element of the set.
 func (s *Set) Contains(n int) bool{
  if n < 0{
  return false
@@ -114,8 +116,8 @@ func (s1 *Set) Subset(s2 *Set) bool{
  return true
 }
 
-// Max returns the maximum element of the set.
-// It panics if the set is empty.
+// Max returns the maximum element of the set;
+// it panics if the set is empty.
 func (s *Set) Max() int{
  if len(s.data) == 0{
  panic("max not defined for empty set")
@@ -125,7 +127,7 @@ func (s *Set) Max() int{
  return i<<shift + 63 - LeadingZeros(d[i])
 }
 
-// Size returns the number of elements in this set.
+// Size returns the number of elements in the set.
 // This method scans the set; to check if a set is empty,
 // consider using the more efficient Empty method.
 func (s *Set) Size() int{
@@ -139,7 +141,7 @@ func (s *Set) Size() int{
  return n
 }
 
-// Empty tells if this set is empty.
+// Empty tells if the set is empty.
 func (s *Set) Empty() bool{
  return len(s.data) == 0
 }
@@ -390,7 +392,7 @@ func (s1 *Set) AndNot(s2 *Set) *Set{
  return new(Set).SetAndNot(s1, s2)
 }
 
-// Set sets s to s1 and then returns a pointer to s.
+// Set sets s to s1 and then returns a pointer to the updated set s.
 func (s *Set) Set(s1 *Set) *Set{
  s.realloc(len(s1.data))
  copy(s.data, s1.data)

set_test.go

@@ -199,6 +199,7 @@ func TestEmpty(t *testing.T){
  }{
 {New(), true},
 {New(-1), true},
+{New().AddRange(-10, 0), true},
 {New(1), false},
 {New(65), false},
 {New(1, 2, 3), false},