bitio

README

bit-io

I/O for bits.

Documentation

Overview

Package bitio provides types for I/O with bits.

Index

• type Bit
• type Bits
• type Reader
  • func NewReader(r io.Reader, chunkSize int) *Reader
  • func (r *Reader) ReadBit() (Bit, error)
  • func (r *Reader) ReadBits(n int) (bits Bits, read int, err error)
• type Writer
  • func NewWriter(w io.Writer, chunkSize int) *Writer
  • func (w *Writer) Commit() (written int, err error)
  • func (w *Writer) CommitPending() (written int, err error)
  • func (w Writer) HasPendingBits() bool
  • func (w *Writer) WriteBit(b Bit) (written int, err error)
  • func (w *Writer) WriteBits(bits Bits, length int) (written int, err error)

Examples

• Reader.ReadBits
• Writer
• Writer.WriteBits

Types

type Bit

type Bit = byte

Bit is mainly for documentation purposes, and to help clarify the expected return value.

type Bits

type Bits = uint

Bits is one or more bits collected into an int. It is mainly for documentation purposes.

type Reader

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

Reader reads the bits from a reader that reads bytes.

Assuming bytes are little-endian, reading occurs from left to right.

func NewReader

func NewReader(r io.Reader, chunkSize int) *Reader

NewReader creates a new bit reader. The amount of bytes to be read at a time is set by chunkSize.

func (*Reader) ReadBit

func (r *Reader) ReadBit() (Bit, error)

ReadBit reads a single bit.

func (*Reader) ReadBits

func (r *Reader) ReadBits(n int) (bits Bits, read int, err error)

ReadBits reads attempts to read n bits, and returns those bits collected into an int, the actual amount read, and any error that might have occurred.

Example

buff := bytes.NewBuffer([]byte{0x12, 0x34, 0x56})
r := bitio.NewReader(buff, 3)

for i := 0; i < 2; i++ {
	bits, _, err := r.ReadBits(12)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("0x%03X\n", bits)
}

Output:

0x123
0x456

type Writer

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

Writer writes bits to an io.Writer

Assuming bytes are little-endian, writing occurs from left to right.

Example

A Writer writes bits to the underlying writer, but only when a "chunk" is filled. To write a partial chunk (for example, half of a bit), the write must be committed.

var buff bytes.Buffer

// A writer with a chunk size of 2 bytes.
w := bitio.NewWriter(&buff, 2)

// 12 1 bits written. A chunk requires 16 bits (2 bytes), so the write is currently
// pending.
written, _ := w.WriteBits(0xFFF, 12)
fmt.Printf("%d bits written\n", written)

// Now we commit the pending bits.
written, _ = w.CommitPending()
fmt.Printf("%d bits written\n", written)

for i, b := range buff.Bytes() {
	fmt.Printf("byte %d = 0x%02X\n", i, b)
}

Output:

0 bits written
16 bits written
byte 0 = 0xFF
byte 1 = 0xF0

func NewWriter

func NewWriter(w io.Writer, chunkSize int) *Writer

NewWriter creates a new bit writer. The amount of full bytes to write at a time is set by chunkSize.

func (*Writer) Commit

func (w *Writer) Commit() (written int, err error)

Commit commits the current bytes to the writer, even if a byte is only partially written. Partial bytes will be zero-filled. A commit will happen any time that a write would overflow the current chunk.

The number of bits written are returned, and any error that occurred when writing.

Deprecated: Use CommitPending instead. If it is necessary to write a chunk of unset bits, it is preferred to use WriteBit or WriteBits to write the unset bits instead of using Commit to force an empty chunk to be written.

func (*Writer) CommitPending

func (w *Writer) CommitPending() (written int, err error)

CommitPending is a helper function that commits the current written bits only if the byte chunk is partially written. Does nothing if the byte chunk is empty.

If it is unknown if the number of bits written will completely fill all chunks, then it is recommended to execute this once to conclude writing.

func (Writer) HasPendingBits

func (w Writer) HasPendingBits() bool

HasPendingBits returns true if there are any bits that are pending, but have not yet been written to the underlying writer. For example, if half of a byte is written, then there are 4 pending bits.

func (*Writer) WriteBit

func (w *Writer) WriteBit(b Bit) (written int, err error)

WriteBit writes a single bit.

The number of bits written will be returned, which will be 0 until a chunk is filled.

func (*Writer) WriteBits

func (w *Writer) WriteBits(bits Bits, length int) (written int, err error)

WriteBits writes multiple bits from an int.

Bits will be interpreted from the left to the right bit (assuming the int is little-endian).

Length is used to specify the number of bits to write, to remove ambiguity between an "empty" set of bits and a long string of 0s. Length specifies the left-most bit.

The number of bits written will be returned, which will be 0 if a chunk wasn't filled.

Example

var buff bytes.Buffer
w := bitio.NewWriter(&buff, 3)

if _, err := w.WriteBits(0x123456, 24); err != nil {
	log.Fatal(err)
}

for _, b := range buff.Bytes() {
	fmt.Printf("0x%02X\n", b)
}

Output:

0x12
0x34
0x56