bitstring

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2021 License: MIT Imports: 5 Imported by: 0

README

go.dev reference Test Actions Status Go Report Card codecov

bitstring

Go bitstring library

Package bitstring implements an fixed-length bit string type and many bit string 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
  • Trailing/Leading zeroes/ones
  • improve documentation

Documentation

Overview

Package bitstring implements a fixed length bit string type and bit string manipulation functions

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Copy 

func Copy(dst, src *Bitstring)

Copy copies a source Bitstring into a destination Bitstring, shrinking or expanding it if necessary.

func EqualRange 

func EqualRange(bs1, bs2 *Bitstring, start, length int) bool

EqualRange compares a given range of bits between 2 bitstrings.

It's like Equals but only compares the [start, start+length) range. EqualRange returns false if this range is not defined on both bitstrings.

func SwapRange 

func SwapRange(bs1, bs2 *Bitstring, start, length int)

SwapRange swaps a range of bits between 2 bitstrings.

The range [start, start+length) must exist on both bitstrings or SwapRange has undefined behavior.

Example 
bs1, _ := NewFromString("111")
bs2, _ := NewFromString("000")
// Swap 2 bits from index 0
SwapRange(bs1, bs2, 2, 1)
fmt.Println(bs1)

Output:

011

Types

type Bitstring 

type Bitstring struct {
	// contains filtered or unexported fields
}

Bitstring implements a fixed-length bit string.

Internally, bits are packed into an array of machine word integers. This implementation makes more efficient use of space than the alternative approach of using an array of booleans.

func Clone 

func Clone(src *Bitstring) *Bitstring

Clone creates and returns a new Bitstring that is a clone of src.

func New 

func New(length int) *Bitstring

New creates a bit string of the specified length (in bits) with all bits initially set to zero (off).

Example 
// Create a 32-bit Bitstring
bs := New(32)
// upon creation all bits are unset
fmt.Println(bs)

Output:

00000000000000000000000000000000

func NewFromString 

func NewFromString(s string) (*Bitstring, error)

NewFromString returns the corresponding Bitstring for the given string of 1s and 0s in big endian order.

Example 
// Create a Bitstring from a string made of 0's and 1's.
bs, _ := NewFromString("101001")
fmt.Println(bs)
fmt.Println(bs.Len(), "bits")

Output:

101001
6 bits

func Random 

func Random(length int, rng *rand.Rand) *Bitstring

Random creates a Bitstring of the length l in which each bit is assigned a random value using rng.

Random randomly sets the uint32 values of the underlying slice, so it should be faster than creating a bit string and then randomly setting each individual bits.

func (*Bitstring) BigInt 

func (bs *Bitstring) BigInt() *big.Int

BigInt returns the big.Int representation of bs.

Example 
bs, _ := NewFromString("100")
bi := bs.BigInt()
fmt.Println(bi.Int64())

Output:

4

func (*Bitstring) Bit 

func (bs *Bitstring) Bit(i int) bool

Bit returns a boolean indicating wether the bit at index i is set or not.

If i is greater than the bitstring length, Bit will panic.

func (*Bitstring) ClearBit 

func (bs *Bitstring) ClearBit(i int)

ClearBit clears the bit at index i.

If i is greater than the bitstring length, ClearBit will panic.

Example 
bs := New(8)
bs.SetBit(2)
fmt.Println(bs)
bs.ClearBit(2)
fmt.Println(bs)

Output:

00000100
00000000

func (*Bitstring) ClearRange 

func (bs *Bitstring) ClearRange(start, length int)

ClearRange clears a range of bits (sets all bits to 0).

The range [start, start+length) must exist or ClearRange has undefined behavior.

Example 
bs, _ := NewFromString("10101010")
// Clear the 3 bits at offset 2.
bs.ClearRange(2, 3)
fmt.Println(bs)

Output:

10100010

func (*Bitstring) Data 

func (bs *Bitstring) Data() []uint64

Data returns the bitstring underlying slice.

func (*Bitstring) Equals 

func (bs *Bitstring) Equals(other *Bitstring) bool

Equals returns true if bs and other have the same length and each bit are identical, or if bs and other both point to the same Bitstring instance (i.e pointer equality).

func (*Bitstring) FlipBit 

func (bs *Bitstring) FlipBit(i int)

FlipBit flips (i.e toggles) the bit at index i.

If i is greater than the bitstring length, FlipBit will panic.

Example 
bs := New(8)
bs.FlipBit(2)
fmt.Println(bs)

Output:

00000100

func (*Bitstring) FlipRange 

func (bs *Bitstring) FlipRange(start, length int)

FlipRange flips a range of bits (flips the value of every bit).

The range [start, start+length) must exist or FlipRange has undefined behavior.

Example 
bs, _ := NewFromString("10101010")
// Flip the 3 bits at offset 2.
bs.FlipRange(2, 3)
fmt.Println(bs)

Output:

10110110

func (*Bitstring) Gray16 

func (bs *Bitstring) Gray16(i int) uint16

Gray16 returns the uint8 value represented by the 16 gray-coded bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Gray32 

func (bs *Bitstring) Gray32(i int) uint32

Gray32 returns the uint32 value represented by the 32 gray-coded bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Gray64 

func (bs *Bitstring) Gray64(i int) uint64

Gray64 returns the uint64 value represented by the 64 gray-coded bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Gray8 

func (bs *Bitstring) Gray8(i int) uint8

Gray8 returns the uint8 value represented by the 8 gray-coded bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Grayn 

func (bs *Bitstring) Grayn(nbits, i int) uint64

Grayn returns the n-bit unsigned integer value represented by the n gray-coded bits starting at the bit index i. It panics if there are not enough bits or if n is greater than the size of a machine word.

func (*Bitstring) Int16 

func (bs *Bitstring) Int16(i int) int16

Int16 returns the int16 value represented by the 16 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Int32 

func (bs *Bitstring) Int32(i int) int32

Int32 returns the int32 value represented by the 32 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Int64 

func (bs *Bitstring) Int64(i int) int64

Int64 returns the int64 value represented by the 64 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Int8 

func (bs *Bitstring) Int8(i int) int8

Int8 returns the int8 value represented by the 8 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Intn 

func (bs *Bitstring) Intn(nbits, i int) int32

Intn returns the n-bit signed integer value represented by the n bits starting at the i. It panics if there are not enough bits or if n is greater than the size of a machine word.

func (*Bitstring) Len 

func (bs *Bitstring) Len() int

Len returns the length if bs, that is the number of bits it contains.

func (*Bitstring) OnesCount 

func (bs *Bitstring) OnesCount() int

OnesCount counts the number of one bits.

Example 
bitstring := New(8)
fmt.Println(bitstring.OnesCount())

Output:

0

func (*Bitstring) SetBit 

func (bs *Bitstring) SetBit(i int)

SetBit sets the bit at index i.

If i is greater than the bitstring length, SetBit will panic.

Example 
bs := New(8)
bs.SetBit(2)
fmt.Println("bit 2:", bs.Bit(2))
fmt.Println("bit 7:", bs.Bit(7))

Output:

bit 2: true
bit 7: false

func (*Bitstring) SetInt16 

func (bs *Bitstring) SetInt16(i int, x int16)

SetInt16 sets the 16 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetInt32 

func (bs *Bitstring) SetInt32(i int, x int32)

SetInt32 sets the 32 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetInt64 

func (bs *Bitstring) SetInt64(i int, x int64)

SetInt64 sets the 64 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetInt8 

func (bs *Bitstring) SetInt8(i int, x int8)

SetInt8 sets the 8 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetIntn 

func (bs *Bitstring) SetIntn(n, i int, x int64)

SetIntn sets the n bits starting at i with the first n bits of value x. It panics if there aren't enough bits in bs or if n is greater than 64.

func (*Bitstring) SetRange 

func (bs *Bitstring) SetRange(start, length int)

SetRange sets a range of bits (sets all bits to 1).

The range [start, start+length) must exist or SetBitRange has undefined behavior.

Example 
bs, _ := NewFromString("10101010")
// Set the 3 bits at offset 2.
bs.SetRange(2, 3)
fmt.Println(bs)

Output:

10111110

func (*Bitstring) SetUint16 

func (bs *Bitstring) SetUint16(i int, x uint16)

SetUint16 sets the 16 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetUint32 

func (bs *Bitstring) SetUint32(i int, x uint32)

SetUint32 sets the 32 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetUint64 

func (bs *Bitstring) SetUint64(i int, x uint64)

SetUint64 sets the 64 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetUint8 

func (bs *Bitstring) SetUint8(i int, x uint8)

SetUint8 sets the 8 bits starting at i with the value of x. It panics if there are not enough bits.

func (*Bitstring) SetUintn 

func (bs *Bitstring) SetUintn(n, i int, x uint64)

SetUintn sets the n bits starting at i with the first n bits of value x. It panics if there aren't enough bits in bs or if n is greater than the size of a machine word.

func (*Bitstring) String 

func (bs *Bitstring) String() string

String returns a string representation of bs in big endian order.

func (*Bitstring) Uint16 

func (bs *Bitstring) Uint16(i int) uint16

Uint16 returns the uint16 value represented by the 16 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Uint32 

func (bs *Bitstring) Uint32(i int) uint32

Uint32 returns the uint32 value represented by the 32 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Uint64 

func (bs *Bitstring) Uint64(i int) uint64

Uint64 returns the uint64 value represented by the 64 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Uint8 

func (bs *Bitstring) Uint8(i int) uint8

Uint8 returns the uint8 value represented by the 8 bits starting at the given bit. It panics if there are not enough bits.

func (*Bitstring) Uintn 

func (bs *Bitstring) Uintn(n, i int) uint64

Uintn returns the n bits unsigned integer value represented by the n bits starting at the bit index i. It panics if there aren't enough bits in bs or if n is greater than the size of a machine word. TODO: reverse order of nbits and i params

func (*Bitstring) ZeroesCount 

func (bs *Bitstring) ZeroesCount() int

ZeroesCount counts the number of zero bits.

Example 
bs := New(8)
fmt.Println(bs.ZeroesCount())

Output:

8

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.