bitset

README

BitSet Go Package

The bitset package provides a simple and efficient implementation of a bitmap data structure in Go, allowing you to store and manipulate individual bits. It is ideal for use cases where you need to work with large sets of bits and perform operations such as checking, setting, and clearing bits.

Installation

To install the package, use:

go get github.com/axkit/bitset

Overview

The bitset package provides the BitSet interface and its implementation ByteBitSet, which stores bits as a slice of bytes. Each bit is represented by a single bit within a byte, with the leftmost bit in the first byte representing the first bit, and the least significant bit in the last byte representing the last bit.

Features

•	Create BitSet: Initialize a new bitset with a specified size or from a hexadecimal or binary string.
•	Set/Unset Bits: Set or unset bits at specified positions.
•	Check Bits: Check if specific bits are set, using both All and Any rules.
•	Convert to String: Convert the bitset to hexadecimal or binary string formats.
•	Clone: Create a deep copy of an existing bitset.

Examples

Bit Representation

1000 0010  ->  Hexadecimal: "82" (bits 0 and 6 are set)
1000 0011  ->  Hexadecimal: "83" (bits 0, 6, and 7 are set)
1100 0001 1100 0011  ->  Hexadecimal: "c1c3" (bits 0, 1, 7, 8, 9, 14, 15 are set)

Usage

Creating a New BitSet

You can create a new BitSet by specifying the number of bits to allocate:

import "github.com/yourusername/bitset"

bs := bitset.New(16) // Creates a BitSet with space for 16 bits

Alternatively, you can initialize it from a hexadecimal string:

bs, err := bitset.NewFromString("82")
if err != nil {
    fmt.Println("Error:", err)
}

Setting and Checking Bits

Set specific bits:

bs.Set(true, 0, 6) // Sets bits 0 and 6

Check if a bit is set:

if bs.IsSet(0) {
    fmt.Println("Bit 0 is set")
}

Checking Multiple Bits

You can check if all or any bits are set using All or Any rules:

if bs.AreSet(bitset.All, 0, 6) {
    fmt.Println("Bits 0 and 6 are both set")
}

if bs.AreSet(bitset.Any, 0, 7) {
    fmt.Println("At least one of the bits 0 or 7 is set")
}

Converting to String Representations

To get the hexadecimal or binary string representation of the bitset:

hexStr := bs.String()
fmt.Println("Hexadecimal:", hexStr)

binStr := bs.BinaryString()
fmt.Println("Binary:", binStr)

Cloning a BitSet

You can create a deep copy of an existing BitSet:

clone := bitset.Clone(bs)

Errors

ErrParseFailed

Returned by parsing functions when an invalid character is encountered.

ErrInvalidSourceString

Indicates an invalid source string, such as an odd-length string in hexadecimal input.

License

This package is open-source and distributed under the MIT License. Contributions and feedback are welcome!

Documentation

Overview

The package provides typical bitmap storage and manipulation functions. BitSet is a data structure that holds a set of bits. Each bit is represented by a single bit in the byte slice. The first bit is stored in the left bit of the first byte, and the last bit is stored in the least significant bit of the last byte. Examples:

1000 0010 where bits 0,6 is set in the string representation will look like hex string "82" 1000 0011 where bits 0, 6, 7 is set in the string representation will look like hes string "83" 1100 0001 1100 0011 where bits 0,1,7, 8,9, 14,15 us set in the string representation will look like "c1c3"

Index

• Variables
• func AreSet(buf []byte, rule CompareRule, bitpos ...uint) (bool, error)
• func Validate(buf []byte) error
• type BitSet
  • func Clone(bs BitSet) BitSet
  • func NewFromBinaryString(src string) (BitSet, error)
• type ByteBitSet
  • func New(bitSize int) *ByteBitSet
  • func NewFromBytes(buf []byte) (ByteBitSet, error)
  • func NewFromString(src string) (ByteBitSet, error)
  • func (bs *ByteBitSet) AreSet(rule CompareRule, bitpos ...uint) bool
  • func (bs *ByteBitSet) BinaryString() string
  • func (bs *ByteBitSet) Bytes() []byte
  • func (bs *ByteBitSet) Empty() bool
  • func (bs *ByteBitSet) IsAllocated(bitpos uint) bool
  • func (bs *ByteBitSet) IsSet(bitpos uint) bool
  • func (bs *ByteBitSet) Len() uint
  • func (bs *ByteBitSet) Set(val bool, bitpos ...uint) BitSet
  • func (bs *ByteBitSet) String() string
• type CompareRule

Variables

var (
	ErrParseFailed         = errors.New("invalid character found")
	ErrInvalidSourceString = errors.New("invalid source string")
)

ErrParseFailed is returned by the Parse function when an invalid character is found in the input string. Valid characters are 0-9, a-f, A-F.

Functions

func AreSet

func AreSet(buf []byte, rule CompareRule, bitpos ...uint) (bool, error)

AreSet receives a hexadecimal string representation of a BitSet and checks if all specified bits are set to 1.

func Validate

func Validate(buf []byte) error

Types

type BitSet

type BitSet interface {
	IsSet(pos uint) bool
	AreSet(rule CompareRule, bitpos ...uint) bool
	Set(val bool, bitpos ...uint) BitSet
	Empty() bool
	String() string
	Bytes() []byte
}

func Clone

func Clone(bs BitSet) BitSet

Clone returns a deep copy of the given BitSet. It creates a new BitSet and copies the mask from the source BitSet.

func NewFromBinaryString

func NewFromBinaryString(src string) (BitSet, error)

type ByteBitSet

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

ByteBitSet holds a set of bits using a slice of bytes. Each bit in the bitset is represented by one bit in the byte slice.

func New

func New(bitSize int) *ByteBitSet

New creates a BitSet with allocated space for the specified number of bits. It takes the bit size as input, calculates how many bytes are needed to store that many bits, and returns a pointer to a new BitSet.

func NewFromBytes

func NewFromBytes(buf []byte) (ByteBitSet, error)

NewFromBytes converts a hexadecimal byte slice into a BitSet. It returns an error if any of the input characters are not valid hexadecimal digits.

func NewFromString

func NewFromString(src string) (ByteBitSet, error)

func (*ByteBitSet) AreSet

func (bs *ByteBitSet) AreSet(rule CompareRule, bitpos ...uint) bool

AreSet checks if all or any of the specified bits are set to 1. If any of the bits is not set, or if the bitset is empty, it returns false.

func (*ByteBitSet) BinaryString

func (bs *ByteBitSet) BinaryString() string

BinaryString returns binary representation of the bitset. Each byte in the bitset is converted to 8 characters (0 or 1). Zero bit of the bitset will be at the end of the string.

func (*ByteBitSet) Bytes

func (bs *ByteBitSet) Bytes() []byte

Bytes returns the internal representation of the bitset as a byte slice.

func (*ByteBitSet) Empty

func (bs *ByteBitSet) Empty() bool

Empty returns true if BitSet is not initialized.

func (*ByteBitSet) IsAllocated

func (bs *ByteBitSet) IsAllocated(bitpos uint) bool

IsAllocated returns true if the space for the specified bit is already allocated. It checks whether the internal storage has enough space for the given bit position.

func (*ByteBitSet) IsSet

func (bs *ByteBitSet) IsSet(bitpos uint) bool

IsSet returns true if the bit at the specified position is set (i.e., 1). If the position is beyond the current length of the bitset, it returns false.

func (*ByteBitSet) Len

func (bs *ByteBitSet) Len() uint

Len returns the length of the allocated bitset in bits. The length is calculated by multiplying the number of bytes in the mask by 8.

func (*ByteBitSet) Set

func (bs *ByteBitSet) Set(val bool, bitpos ...uint) BitSet

Set sets the specified bits to 1. If the bit position is out of range, the internal byte slice is automatically extended to accommodate the bit.

func (*ByteBitSet) String

func (bs *ByteBitSet) String() string

String returns a hexadecimal representation of the bitset. Each byte in the bitset is converted to two hexadecimal characters.

type CompareRule

type CompareRule int8

const (
	All CompareRule = iota
	Any
)