README.md
1# bitset
2
3*Go language library to map between non-negative integers and boolean values*
4
5[](https://travis-ci.org/willf/bitset?branch=master)
6[](https://coveralls.io/github/willf/bitset?branch=master)
7[](https://goreportcard.com/report/github.com/willf/bitset)
8[](http://godoc.org/github.com/willf/bitset)
9
10
11## Description
12
13Package bitset implements bitsets, a mapping between non-negative integers and boolean values.
14It should be more efficient than map[uint] bool.
15
16It provides methods for setting, clearing, flipping, and testing individual integers.
17
18But it also provides set intersection, union, difference, complement, and symmetric operations, as well as tests to check whether any, all, or no bits are set, and querying a bitset's current length and number of positive bits.
19
20BitSets are expanded to the size of the largest set bit; the memory allocation is approximately Max bits, where Max is the largest set bit. BitSets are never shrunk. On creation, a hint can be given for the number of bits that will be used.
21
22Many of the methods, including Set, Clear, and Flip, return a BitSet pointer, which allows for chaining.
23
24### Example use:
25
26```go
27package main
28
29import (
30 "fmt"
31 "math/rand"
32
33 "github.com/willf/bitset"
34)
35
36func main() {
37 fmt.Printf("Hello from BitSet!\n")
38 var b bitset.BitSet
39 // play some Go Fish
40 for i := 0; i < 100; i++ {
41 card1 := uint(rand.Intn(52))
42 card2 := uint(rand.Intn(52))
43 b.Set(card1)
44 if b.Test(card2) {
45 fmt.Println("Go Fish!")
46 }
47 b.Clear(card1)
48 }
49
50 // Chaining
51 b.Set(10).Set(11)
52
53 for i, e := b.NextSet(0); e; i, e = b.NextSet(i + 1) {
54 fmt.Println("The following bit is set:", i)
55 }
56 if b.Intersection(bitset.New(100).Set(10)).Count() == 1 {
57 fmt.Println("Intersection works.")
58 } else {
59 fmt.Println("Intersection doesn't work???")
60 }
61}
62```
63
64As an alternative to BitSets, one should check out the 'big' package, which provides a (less set-theoretical) view of bitsets.
65
66Godoc documentation is at: https://godoc.org/github.com/willf/bitset
67
68
69## Implementation Note
70
71Go 1.9 introduced a native `math/bits` library. We provide backward compatibility to Go 1.7, which might be removed.
72
73It is possible that a later version will match the `math/bits` return signature for counts (which is `int`, rather than our library's `unit64`). If so, the version will be bumped.
74
75## Installation
76
77```bash
78go get github.com/willf/bitset
79```
80
81## Contributing
82
83If you wish to contribute to this project, please branch and issue a pull request against master ("[GitHub Flow](https://guides.github.com/introduction/flow/)")
84
85This project include a Makefile that allows you to test and build the project with simple commands.
86To see all available options:
87```bash
88make help
89```
90
91## Running all tests
92
93Before committing the code, please check if it passes all tests using (note: this will install some dependencies):
94```bash
95make qa
96```
97
){kind=link}
){kind=link}
){kind=link}