160 lines
4.8 KiB
Markdown
160 lines
4.8 KiB
Markdown
# bitset
|
|
|
|
*Go language library to map between non-negative integers and boolean values*
|
|
|
|
[](https://github.com/willf/bitset/actions?query=workflow%3ATest)
|
|
[](https://goreportcard.com/report/github.com/willf/bitset)
|
|
[](https://pkg.go.dev/github.com/bits-and-blooms/bitset?tab=doc)
|
|
|
|
|
|
This library is part of the [awesome go collection](https://github.com/avelino/awesome-go). It is used in production by several important systems:
|
|
|
|
* [beego](https://github.com/beego/beego)
|
|
* [CubeFS](https://github.com/cubefs/cubefs)
|
|
* [Amazon EKS Distro](https://github.com/aws/eks-distro)
|
|
* [sourcegraph](https://github.com/sourcegraph/sourcegraph)
|
|
* [torrent](https://github.com/anacrolix/torrent)
|
|
|
|
|
|
## Description
|
|
|
|
Package bitset implements bitsets, a mapping between non-negative integers and boolean values.
|
|
It should be more efficient than map[uint] bool.
|
|
|
|
It provides methods for setting, clearing, flipping, and testing individual integers.
|
|
|
|
But 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.
|
|
|
|
BitSets 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.
|
|
|
|
Many of the methods, including Set, Clear, and Flip, return a BitSet pointer, which allows for chaining.
|
|
|
|
### Example use:
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"fmt"
|
|
"math/rand"
|
|
|
|
"github.com/bits-and-blooms/bitset"
|
|
)
|
|
|
|
func main() {
|
|
fmt.Printf("Hello from BitSet!\n")
|
|
var b bitset.BitSet
|
|
// play some Go Fish
|
|
for i := 0; i < 100; i++ {
|
|
card1 := uint(rand.Intn(52))
|
|
card2 := uint(rand.Intn(52))
|
|
b.Set(card1)
|
|
if b.Test(card2) {
|
|
fmt.Println("Go Fish!")
|
|
}
|
|
b.Clear(card1)
|
|
}
|
|
|
|
// Chaining
|
|
b.Set(10).Set(11)
|
|
|
|
for i, e := b.NextSet(0); e; i, e = b.NextSet(i + 1) {
|
|
fmt.Println("The following bit is set:", i)
|
|
}
|
|
if b.Intersection(bitset.New(100).Set(10)).Count() == 1 {
|
|
fmt.Println("Intersection works.")
|
|
} else {
|
|
fmt.Println("Intersection doesn't work???")
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
Package documentation is at: https://pkg.go.dev/github.com/bits-and-blooms/bitset?tab=doc
|
|
|
|
## Serialization
|
|
|
|
|
|
You may serialize a bitset safely and portably to a stream
|
|
of bytes as follows:
|
|
```Go
|
|
const length = 9585
|
|
const oneEvery = 97
|
|
bs := bitset.New(length)
|
|
// Add some bits
|
|
for i := uint(0); i < length; i += oneEvery {
|
|
bs = bs.Set(i)
|
|
}
|
|
|
|
var buf bytes.Buffer
|
|
n, err := bs.WriteTo(&buf)
|
|
if err != nil {
|
|
// failure
|
|
}
|
|
// Here n == buf.Len()
|
|
```
|
|
You can later deserialize the result as follows:
|
|
|
|
```Go
|
|
// Read back from buf
|
|
bs = bitset.New()
|
|
n, err = bs.ReadFrom(&buf)
|
|
if err != nil {
|
|
// error
|
|
}
|
|
// n is the number of bytes read
|
|
```
|
|
|
|
The `ReadFrom` function attempts to read the data into the existing
|
|
BitSet instance, to minimize memory allocations.
|
|
|
|
|
|
*Performance tip*:
|
|
When reading and writing to a file or a network connection, you may get better performance by
|
|
wrapping your streams with `bufio` instances.
|
|
|
|
E.g.,
|
|
```Go
|
|
f, err := os.Create("myfile")
|
|
w := bufio.NewWriter(f)
|
|
```
|
|
```Go
|
|
f, err := os.Open("myfile")
|
|
r := bufio.NewReader(f)
|
|
```
|
|
|
|
## Memory Usage
|
|
|
|
The memory usage of a bitset using `N` bits is at least `N/8` bytes. The number of bits in a bitset is at least as large as one plus the greatest bit index you have accessed. Thus it is possible to run out of memory while using a bitset. If you have lots of bits, you might prefer compressed bitsets, like the [Roaring bitmaps](http://roaringbitmap.org) and its [Go implementation](https://github.com/RoaringBitmap/roaring).
|
|
|
|
The `roaring` library allows you to go back and forth between compressed Roaring bitmaps and the conventional bitset instances:
|
|
```Go
|
|
mybitset := roaringbitmap.ToBitSet()
|
|
newroaringbitmap := roaring.FromBitSet(mybitset)
|
|
```
|
|
|
|
|
|
## Implementation Note
|
|
|
|
Go 1.9 introduced a native `math/bits` library. We provide backward compatibility to Go 1.7, which might be removed.
|
|
|
|
It is possible that a later version will match the `math/bits` return signature for counts (which is `int`, rather than our library's `uint64`). If so, the version will be bumped.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go get github.com/bits-and-blooms/bitset
|
|
```
|
|
|
|
## Contributing
|
|
|
|
If you wish to contribute to this project, please branch and issue a pull request against master ("[GitHub Flow](https://guides.github.com/introduction/flow/)")
|
|
|
|
## Running all tests
|
|
|
|
Before committing the code, please check if it passes tests, has adequate coverage, etc.
|
|
```bash
|
|
go test
|
|
go test -cover
|
|
```
|