github.com/tunabay/go-bitarray@v1.3.1/README.md (about)

     1  # go-bitarray
     2  
     3  [![Go Reference](https://pkg.go.dev/badge/github.com/tunabay/go-bitarray.svg)](https://pkg.go.dev/github.com/tunabay/go-bitarray)
     4  [![MIT License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)
     5  
     6  ## Overview
     7  
     8  Package bitarray provides data types and functions for manipulating bit arrays,
     9  aka bit strings, of arbitrary length.
    10  
    11  This is designed to handle bit arrays across byte boundaries naturally, without
    12  error-prone bitwise operation code such as shifting, masking, and ORing. It may
    13  be useful when dealing with Huffman coding, raw packet of various protocols, and
    14  binary file formats, etc.
    15  
    16  ## Usage
    17  
    18  ### Manipulate bitarrays using the `BitArray` type.
    19  ```go
    20  import (
    21  	"fmt"
    22  	"github.com/tunabay/go-bitarray"
    23  )
    24  
    25  func main() {
    26  	// Parse string representation
    27  	ba1, err := bitarray.Parse("111000")
    28  	if err != nil {
    29  		panic(err)
    30  	}
    31  	fmt.Println(ba1) // 111000
    32  
    33  	// Slice and Repeat
    34  	ba2 := ba1.Slice(2, 5).Repeat(2)
    35  	fmt.Println(ba2) // 100100
    36  
    37  	// Append
    38  	ba3 := ba2.Append(bitarray.MustParse("101011"))
    39  	// alternative formatting
    40  	fmt.Printf("% b\n", ba3) // 10010010 1011
    41  
    42  	// Extract bits from []byte across byte boundary
    43  	buf := []byte{0xff, 0x00}
    44  	ba4 := bitarray.NewFromBytes(buf, 4, 7)
    45  	fmt.Println(ba4) // 1111000
    46  }
    47  ```
    48  [Run in Go Playground](https://play.golang.org/p/qm4fpMCPdWa)
    49  
    50  ### Use the `Buffer` type for bitwise access to byte slices.
    51  ```go
    52  import (
    53  	"fmt"
    54  	"github.com/tunabay/go-bitarray"
    55  )
    56  
    57  // This example assumes 8-byte data with the following bit layout, and
    58  // accesses the 5-bit integer X and the 50-bit integer Y in it.
    59  //
    60  // |0              |1              |2              |3              |
    61  // |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|
    62  // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    63  // | 9-bit flag area | 5-bit X | Upper 18 bits of the 50-bit int Y |
    64  // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    65  // |               Lower 32 bits of the 50-bit int Y               |
    66  // +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    67  func main() {
    68  	data := make([]byte, 8)
    69  	buf := bitarray.NewBufferFromByteSlice(data)
    70  
    71  	// set 9-bit flag area to 110000011
    72  	buf.PutBitAt(0, 1)
    73  	buf.PutBitAt(1, 1)
    74  	buf.PutBitAt(7, 1)
    75  	buf.PutBitAt(8, 1)
    76  
    77  	// set 5-bit integer X
    78  	buf.Slice(9, 14).PutUint8(25) // = 0b_11001
    79  
    80  	// set 50-bit integer Y
    81  	buf.Slice(14, 64).PutUint64(0x_3_f0ff_f0f0_ff0f)
    82  
    83  	// raw bytes updated
    84  	fmt.Printf("%08b\n%08b\n", data[:4], data[4:])
    85  
    86  	// read fields
    87  	fmt.Printf("F = %b\n", buf.Slice(0, 9))
    88  	fmt.Printf("X = %d\n", buf.Slice(9, 14).Uint8())
    89  	fmt.Printf("Y = %x\n", buf.SliceToEnd(14).Uint64())
    90  }
    91  ```
    92  [Run in Go Playground](https://play.golang.org/p/INosZRfZsuR)
    93  
    94  ## Documentation and more examples
    95  
    96  - Read the [documentation](https://pkg.go.dev/github.com/tunabay/go-bitarray).
    97  
    98  ## License
    99  
   100  go-bitarray is available under the MIT license. See the [LICENSE](LICENSE) file for more information.