Various improvements (#6)

* fix typo

* Speedup Equals

Using benchmarks, the threshold of 128 uint64 (1024 bits) is defined.
Above it, bytes.Equal is used after unsafe casting slice header, this
allows very interesting speedups:

name               old time/op    new time/op    delta
Equals/len=100-8     5.30ns ±10%    5.31ns ± 0%     ~     (p=0.429 n=6+5)
Equals/len=500-8     8.28ns ± 6%    8.06ns ± 1%     ~     (p=0.394 n=6+6)
Equals/len=1000-8    11.5ns ± 1%    11.2ns ± 7%     ~     (p=0.065 n=6+6)
Equals/len=2000-8    18.4ns ± 2%    14.8ns ± 9%  -19.62%  (p=0.002 n=6+6)
Equals/len=4000-8    32.6ns ± 2%    18.5ns ± 4%  -43.13%  (p=0.002 n=6+6)
Equals/len=8000-8    67.8ns ± 3%    26.4ns ± 4%  -60.99%  (p=0.002 n=6+6)

* Swap i and nbits in Uintn/Intn methods

* Simplify integer tests

* Improve examples

* Cosmetics and comments

* Inline naive comparison in u64cmp

* EqualRange uses u64cmp

* Improve test coverage

* EqualRange: test all cases

* Cosmetics

* Update README.md

* Cosmetics

* Add Bitstring.CopyRange

* Update README.md

* Cosmetics

* Cosmetics

* bitops: add ispow2()

* Generate reversed bits lookup table

* Add Reverse

* Cosmetics

* Improve Bitstring.Big()

* Factor rightShiftBits

* Make Clone a method

* Add LeadingZeroes and TrailingZeroes

* Use math.MaxUint64 and 64 directly

* Fix BigInt on 32-bit architectures

* Move non-test helpers in helpers.go

* Add lsb and msb functions

* Add NewFromBig

* Add NewFromBig example

Author: arl

README.md

@@ -3,20 +3,36 @@
 [![Go Report Card](https://goreportcard.com/badge/github.com/arl/bitstring)](https://goreportcard.com/report/github.com/arl/bitstring)
 [![codecov](https://codecov.io/gh/arl/bitstring/branch/main/graph/badge.svg)](https://codecov.io/gh/arl/bitstring)
 
-# bitstring
+# `bitstring`
+
 Go bitstring library
 
-Package `bitstring` implements a fixed-length bit string type and many bit manipulation functions:
- - set/clear/flip a single bit 
- - set/clear/flip a range of bits 
- - swap or compare range of bits between 2 bitstrings
- - 8/16/32/64/n signed/unsigned to/from conversions
- - count ones/zeroes
- - gray code conversion methods
- - convert to `big.Int`
- - Copy/Clone methods
-
-TODO:
- - RotateLeft/Right
+Package `bitstring` implements a fixed length bit string type and bit manipulation functions.
+
+ - Get/Set/Clear/Flip a single bit: `Bit`|`SetBit`|`ClearBit`|`FlipBit`
+ - Set/Clear/Flip a range of bits: `SetRange`|`ClearRange`|`FlipRange`
+ - Compare 2 bit strings: `Equals` or `EqualsRange`
+ - 8/16/32/64/N signed/unsigned to/from conversions:
+   - `Uint8`|`Uint16`|`Uint32`|`Uint64`|`Uintn`
+   - `SetUint8`|`SetUint16`|`SetUint32`|`SetUint64`|`SetUintn`
+ - Count ones/zeroes: `ZeroesCount`|`OnesCount`
+ - Gray code conversion methods: `Gray8`|`Gray16`|`Gray32`|`Gray64`|`Grayn`
+ - Convert to/from `big.Int`: `BigInt` | `NewFromBig`
+ - Copy/Clone methods: `Copy`|`Clone`|`CopyRange`
+
+
+# Debug version
+
+By default, bit offsets arguments to `bitstring` methods are not checked. This
+allows not to pay the performance penalty of always checking offsets, in
+environments where they are constants or always known beforehand.
+
+You can enable runtime checks by passing the `bitstring_debug` build tag to `go`
+when building the `bitstring` package.
+
+**TODO**:
+ - RotateLeft/Right ShiftLeft/Right
  - Trailing/Leading zeroes/ones
- - improve documentation
+ - Or, And, Xor between bitstrings
+ - Reverse
+ - Run CI on big|little endian and 32|64 bits (for now only amd64) (see https://github.com/docker/setup-qemu-action)

bench_test.go

@@ -12,7 +12,7 @@ func benchmarkUintn(b *testing.B, nbits, i int) {
 	bs, _ := NewFromString("0000000000000000000000000000000101000000000000000000000000000000")
 	var v uint64
 	for n := 0; n < b.N; n++ {
-		v = bs.Uintn(nbits, i)
+		v = bs.Uintn(i, nbits)
 	}
 	b.StopTimer()
 	sink = v
@@ -102,7 +102,7 @@ func BenchmarkSwapRange(b *testing.B) {
 	b.ResetTimer()
 	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
-		SwapRange(x, y, 1, 1024)
+		SwapRange(x, y, i%26, 1026)
 	}
 }
 
@@ -119,18 +119,27 @@ func BenchmarkRandom(b *testing.B) {
 	sink = x
 }
 
-func BenchmarkEquals(b *testing.B) {
-	rng := rand.New(rand.NewSource(99))
-	x := Random(1026, rng)
-	y := Clone(x)
-	var res bool
-	b.ResetTimer()
-	b.ReportAllocs()
-	for i := 0; i < b.N; i++ {
-		res = x.Equals(y)
+func benchmarkEquals(len int) func(b *testing.B) {
+	return func(b *testing.B) {
+		x, y := New(len), New(len)
+		var res bool
+		b.ResetTimer()
+		b.ReportAllocs()
+		for i := 0; i < b.N; i++ {
+			res = x.Equals(y)
+		}
+		b.StopTimer()
+		sink = res
 	}
-	b.StopTimer()
-	sink = res
+}
+
+func BenchmarkEquals(b *testing.B) {
+	b.Run("len=100", benchmarkEquals(100))
+	b.Run("len=500", benchmarkEquals(500))
+	b.Run("len=1000", benchmarkEquals(1000))
+	b.Run("len=2000", benchmarkEquals(2000))
+	b.Run("len=4000", benchmarkEquals(4000))
+	b.Run("len=8000", benchmarkEquals(8000))
 }
 
 func BenchmarkSetUint8(b *testing.B) {
@@ -149,7 +158,7 @@ func BenchmarkSetUintn(b *testing.B) {
 	b.ResetTimer()
 	b.ReportAllocs()
 	for i := 0; i < b.N; i++ {
-		bs.SetUintn(64, 35, 0x9cfbeb71ee3fcf5f&uintsize)
+		bs.SetUintn(35, 64, 0x9cfbeb71ee3fcf5f&64)
 	}
 	b.StopTimer()
 	sink = bs
@@ -179,11 +188,36 @@ func benchmarkOnesCount(b *testing.B, val string) {
 	sink = ones
 }
 
-// 	var ones uint
-// 	b.ResetTimer()
-// 	b.ReportAllocs()
 func BenchmarkOnesCount(b *testing.B) {
 	for _, tt := range vals {
 		b.Run("", func(b *testing.B) { benchmarkOnesCount(b, tt) })
 	}
 }
+
+func Benchmark_msb(b *testing.B) {
+	nums := []uint64{
+		atobin("1100001000000000000000000000000100000000000000000000000000000000"),
+		atobin("01"),
+		atobin("10"),
+		atobin("10000000000100000000000000000001"),
+		atobin("110000000000100000000000000000001"),
+		atobin("00000000010001111111000000000100"),
+		atobin("00000001000001111111000000000000"),
+		atobin("01000000000000000000000000000000"),
+		atobin("1000000000000000000000000000000000000000000000000000000000000000"),
+		atobin("0100000000000000000000000000000000000000000000000000000000000000"),
+		atobin("1111111111111111111111111111111111111111111111111111111111111111"),
+		atobin("1011111111111111111111111111111111111111111111111111111111111111"),
+		atobin("1111111111111111111111111111111111111111111111111111111111111110"),
+	}
+
+	b.ResetTimer()
+	var val uint64
+	for i := 0; i < b.N; i++ {
+		for _, num := range nums {
+			val = msb(num)
+		}
+	}
+
+	sink = val
+}

bitops.go

@@ -1,60 +1,161 @@
 package bitstring
 
-// bitmask returns a mask where only the nth bit of a uint is set.
+import (
+	"math"
+	"unsafe"
+)
+
+const wordsize = 32 << (^uint(0) >> 63) // 32 or 64
+
+// bitmask returns a mask where only the nth bit of a word is set.
 func bitmask(n uint64) uint64 { return 1 << n }
 
 // wordoffset returns, for a given bit n of a bit string, the offset
-// of the uint that contains bit n.
+// of the word that contains bit n.
 func wordoffset(n uint64) uint64 { return n / 64 }
 
-// bitoffset returns, for a given bit n of a bit string, the offset of
-// that bit with regards to the first bit of the uint that contains it.
+// bitoffset returns, for a given bit n of a bit string, the offset of that bit
+// with respect to the first bit of the word that contains it.
 func bitoffset(n uint64) uint64 { return n & (64 - 1) }
 
-// mask returns a mask that keeps the bits in the range [l, h) behaviour
+// mask returns a mask that keeps the bits in the range [l, h) behavior
 // undefined if any argument is greater than the size of a machine word.
 func mask(l, h uint64) uint64 { return lomask(h) & himask(l) }
 
 // lomask returns a mask to keep the n LSB (least significant bits). Undefined
-// behaviour if n is greater than uintsize.
-func lomask(n uint64) uint64 { return maxuint >> (64 - n) }
+// behavior if n is greater than 64.
+func lomask(n uint64) uint64 { return math.MaxUint64 >> (64 - n) }
 
 // himask returns a mask to keep the n MSB (most significant bits). Undefined
-// behaviour if n is greater than uintsize.
-func himask(n uint64) uint64 { return maxuint << n }
+// behavior if n is greater than 64.
+func himask(n uint64) uint64 { return math.MaxUint64 << n }
 
-// firstSetBit returns the offset of the first set bit in w
-func firstSetBit(w uint64) uint64 {
+// transferbits returns the word that results from transferring some bits from
+// src to dst, where set bits in mask specify the bits to transfer.
+func transferbits(dst, src, mask uint64) uint64 {
+	return dst&^mask | src&mask
+}
+
+// lsb returns the offset of the lowest significant set bit in v. That is, the
+// index of the rightmost 1.
+//
+// Note: lsb(0) is meaningless, it's the caller responsibility to not use the
+// result of lsb(0).
+func lsb(v uint64) uint64 {
 	var num uint64
 
-	if (w & 0xffffffff) == 0 {
+	if (v & 0xffffffff) == 0 {
 		num += 32
-		w >>= 32
+		v >>= 32
 	}
-	if (w & 0xffff) == 0 {
+	if (v & 0xffff) == 0 {
 		num += 16
-		w >>= 16
+		v >>= 16
 	}
-	if (w & 0xff) == 0 {
+	if (v & 0xff) == 0 {
 		num += 8
-		w >>= 8
+		v >>= 8
 	}
-	if (w & 0xf) == 0 {
+	if (v & 0xf) == 0 {
 		num += 4
-		w >>= 4
+		v >>= 4
 	}
-	if (w & 0x3) == 0 {
+	if (v & 0x3) == 0 {
 		num += 2
-		w >>= 2
+		v >>= 2
 	}
-	if (w & 0x1) == 0 {
+	if (v & 0x1) == 0 {
 		num++
 	}
 	return num
 }
 
-// transferbits returns the uint that results from transferring some bits from
-// src to dst, where set bits in mask specify the bits to transfer.
-func transferbits(dst, src, mask uint64) uint64 {
-	return dst&^mask | src&mask
+// msb returns the offset of the most significant set bit in v. That is, the
+// index of the leftmost 1.
+//
+// Note: msb(0) is meaningless, it's the caller responsibility to not use the
+// result of msb(0).
+func msb(v uint64) uint64 {
+	var num uint64
+
+	if (v & 0xffffffff00000000) != 0 {
+		num += 32
+		v >>= 32
+	}
+	if (v & 0xffff0000) != 0 {
+		num += 16
+		v >>= 16
+	}
+	if (v & 0xff00) != 0 {
+		num += 8
+		v >>= 8
+	}
+	if (v & 0xf0) != 0 {
+		num += 4
+		v >>= 4
+	}
+	if (v & 0xc) != 0 {
+		num += 2
+		v >>= 2
+	}
+	if (v & 0x2) != 0 {
+		num++
+		v >>= 1
+	}
+
+	return num
+}
+
+// fastmsbLittleEndian is faster version of msb that only works on little endian
+// architectures. About 50% faster than msb on amd64. Rely on the fact that Go
+// uses IEEE 754 floating point representation. Converts v to float64, then
+// extracts the exponent bits of the IEEE754 representation.
+func fastmsbLittleEndian(v uint64) uint64 {
+	if v == math.MaxUint64 {
+		return 63
+	}
+
+	f := float64(v)
+	arr := *(*[2]uint32)(unsafe.Pointer(&f))
+	return uint64(arr[1]>>20 - 1023)
+}
+
+func reverseBytes(buf []byte) []byte {
+	for i := 0; i < len(buf)/2; i++ {
+		buf[i], buf[len(buf)-i-1] = buf[len(buf)-i-1], buf[i]
+	}
+	return buf
+}
+
+// shifts all words of n bits to the right. invariant: 0 <= off <= 64.
+func rightShiftBits(words []uint64, n uint64) {
+	shift := 64 - n
+	mask := lomask(n)
+	prev := uint64(0) // bits from previous word
+
+	for i := len(words) - 1; i >= 0; i-- {
+		save := (words[i] & mask) << shift
+		words[i] >>= n
+		words[i] |= prev
+		prev = save
+	}
+}
+
+// if n is a power of 2, ispow2 returns (v, true) such that (1<<v) gives n, or
+// (0, false) if n is not a power of 2.
+//
+// panics if n == 0
+func ispow2(n uint64) (uint64, bool) {
+	if (n & -n) != n {
+		// n is not a power of 2
+		return 0, false
+	}
+
+	for i := uint64(0); i < 64; i++ {
+		if n == 1<<i {
+			return i, true
+		}
+	}
+
+	panic("unreachable")
 }