README
¶
go-bits ======= Go-bits is a utility for working with sequences of bits. Read the `package documentation`_ for more information. .. _package documentation: https://godoc.org/github.com/rupertchen/go-bits
Documentation
¶
Overview ¶
Package bits is a set of utilities for working with sequences of bits.
Example (ParsePayload) ¶
// In this example, the payload is presented as a hex-encoded string.
var p, err = ParsePayload("b03a877346aa877346aa")
// Pretty print in JSON for readability.
var pretty, _ = json.MarshalIndent(p, "", " ")
fmt.Println(string(pretty))
fmt.Println(err)
Output: { "Version": 11, "Category": 3, "IsX": true, "IsY": false, "IsZ": true, "Created": "2006-01-02T22:04:05Z", "Modified": "2006-01-02T22:04:05Z" } <nil>
Example (ParsePayloadError) ¶
// The payload has been truncated and does not contain enough bits.
var p, err = ParsePayload("b03a8773")
// Pretty print in JSON for readability.
var pretty, _ = json.MarshalIndent(p, "", " ")
fmt.Println(string(pretty))
fmt.Println(err)
Output: { "Version": 11, "Category": 3, "IsX": true, "IsY": false, "IsZ": true, "Created": "0001-01-01T00:00:00Z", "Modified": "0001-01-01T00:00:00Z" } read time: read bits (index=15, length=32): bits: length extends beyond range
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bitmap ¶
type Bitmap struct {
// contains filtered or unexported fields
}
Bitmap represents a fixed-length, sequence of bits.
func NewBitmap ¶
NewBitmap returns a new Bitmap from a slice of bytes. Passing the output of a decoder is the typical way of creating a Bitmap.
Example (Base64) ¶
// Load bytes from a base64 encoded string.
var b64 = "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQ="
var decoded, err = base64.StdEncoding.DecodeString(b64)
if err != nil {
log.Fatal(err)
}
var bmp = bits.NewBitmap(decoded)
for i := 0; i < 11; i++ {
fmt.Printf("%c", bmp.MustGet(uint(8*i), 8))
}
fmt.Print("\n")
Output: Lorem ipsum
Example (ByteSlice) ¶
// Load bytes from a []byte.
var bmp = bits.NewBitmap([]byte("Hello, World!"))
fmt.Printf("%c%c%c%c%c%c\n",
bmp.MustGet(0, 8),
bmp.MustGet(8, 8),
bmp.MustGet(16, 8),
bmp.MustGet(24, 8),
bmp.MustGet(32, 8),
bmp.MustGet(96, 8),
)
Output: Hello!
Example (HexString) ¶
// Load bytes from a hex encoded string.
var s = "a40c9a21e5a1"
var decoded, err = hex.DecodeString(s)
if err != nil {
log.Fatal(err)
}
var bmp = bits.NewBitmap(decoded)
fmt.Printf("0x%03x\n", bmp.MustGet(0, 12))
fmt.Printf("0x%03x\n", bmp.MustGet(12, 12))
fmt.Printf("0x%03x\n", bmp.MustGet(24, 12))
fmt.Printf("0x%03x\n", bmp.MustGet(36, 12))
Output: 0xa40 0xc9a 0x21e 0x5a1
func NewBitmapFromBlocks ¶
NewBitmapFromBlocks returns a new Bitmap from a slice of Blocks. This a convenient way to explicitly create Bitmaps in code, such as when writing tests.
Example ¶
var bmp = bits.NewBitmapFromBlocks([]bits.Block{
0x0123456789abcdef,
0xfedcba9876543210,
})
fmt.Printf("0x%08x\n", bmp.MustGet(0, 32))
fmt.Printf("0x%08x\n", bmp.MustGet(32, 32))
fmt.Printf("0x%08x\n", bmp.MustGet(64, 32))
fmt.Printf("0x%08x\n", bmp.MustGet(96, 32))
Output: 0x01234567 0x89abcdef 0xfedcba98 0x76543210
func (*Bitmap) Get ¶
Get returns a Block of bits representing the requested range of bits. The returned bits are right-aligned.
func (*Bitmap) MustGet ¶ added in v0.2.0
MustGet returns a Block of bits representing the requested range of bits. The returned bits are right-aligned. It panics if it is unable to return the requested bits.
Example ¶
var bmp = bits.NewBitmap([]byte{0xab, 0xcd, 0xef})
fmt.Printf("0x%016x\n", bmp.MustGet(0, 0))
fmt.Printf("0x%016x\n", bmp.MustGet(0, 4))
fmt.Printf("0x%016x\n", bmp.MustGet(0, 8))
fmt.Printf("0x%016x\n", bmp.MustGet(0, 12))
fmt.Printf("0x%016x\n", bmp.MustGet(0, 16))
fmt.Printf("0x%016x\n", bmp.MustGet(0, 20))
fmt.Printf("0x%016x\n", bmp.MustGet(0, 24))
Output: 0x0000000000000000 0x000000000000000a 0x00000000000000ab 0x0000000000000abc 0x000000000000abcd 0x00000000000abcde 0x0000000000abcdef
type Block ¶
type Block uint64
Block contains a sequence of 0–64 bits. If fewer than 64 bits are needed, the sequence is right-aligned and padded with zeros on the left. It is up to the caller to interpret how many bits are used.
type Reader ¶
type Reader struct {
Err error
// contains filtered or unexported fields
}
Reader provides a convenient way to read bits, up to 64 at a time. Successive calls to the Read* functions will read the next sequence of bits and advance the Reader's position. It is the responsibility of the caller to not read beyond the available range.
Once any Read* call returns an error, all subsequent calls on any Read* function will error, returning the same error as the first. This gives callers the option to "batch" read logic and periodically check for errors rather than checking it after every read.
The internal position is not advanced when there is an error. Therefore, it is possible for NumUnread and HasUnread to return >0 or true, respectively, but be unable to read any more bits. This is an intentional design decision to prevent mis-aligned reads following a read failure.
This is *not* an implementation of io.Reader.
Source Files