bitio

README

bitio

Package bitio provides a highly optimized bit-level Reader and Writer for Go.

You can use Reader.ReadBits() to read arbitrary number of bits from an io.Reader and return it as an uint64, and Writer.WriteBits() to write arbitrary number of bits of an uint64 value to an io.Writer.

Both Reader and Writer also provide highly optimized methods for reading / writing 1 bit of information in the form of a bool value: Reader.ReadBool() and Writer.WriteBool(). These make this package ideal for compression algorithms that use Huffman coding for example, where decision whether to step left or right in the Huffman tree is the most frequent operation.

Reader and Writer give a bit-level view of the underlying io.Reader and io.Writer, but they also provide a byte-level view (io.Reader and io.Writer) at the same time. This means you can also use the Reader.Read() and Writer.Write() methods to read and write slices of bytes. These will give you best performance if the underlying io.Reader and io.Writer are aligned to a byte boundary (else all the individual bytes are assembled from / spread to multiple bytes). You can ensure byte boundary by calling the Align() method of Reader and Writer.

Bit order

The more general highest-bits-first order is used. So for example if the input provides the bytes 0x8f and 0x55:

HEXA    8    f     5    5
BINARY  1100 1111  0101 0101
        aaaa bbbc  ccdd dddd

Then ReadBits will return the following values:

r := NewReader(bytes.NewBuffer([]byte{0x8f, 0x55}))
a, err := r.ReadBits(4) //   1100 = 0x08
b, err := r.ReadBits(3) //    111 = 0x07
c, err := r.ReadBits(3) //    101 = 0x05
d, err := r.ReadBits(6) // 010101 = 0x15

Writing the above values would result in the same sequence of bytes:

b := &bytes.Buffer{}
w := NewWriter(b)
err := w.WriteBits(0x08, 4)
err = w.WriteBits(0x07, 3)
err = w.WriteBits(0x05, 3)
err = w.WriteBits(0x15, 6)
err = w.Close()
// b will hold the bytes: 0x8f and 0x55

Documentation

Overview

Package bitio provides a highly optimized bit-level Reader and Writer.

You can use Reader.ReadBits() to read arbitrary number of bits from an io.Reader and return it as an uint64, and Writer.WriteBits() to write arbitrary number of bits of an uint64 value to an io.Writer.

Both Reader and Writer also provide highly optimized methods for reading / writing 1 bit of information in the form of a bool value: Reader.ReadBool() and Writer.WriteBool(). These make this package ideal for compression algorithms that use Huffman coding for example, where decision whether to step left or right in the Huffman tree is the most frequent operation.

Reader and Writer give a bit-level view of the underlying io.Reader and io.Writer, but they also provide a byte-level view (io.Reader and io.Writer) at the same time. This means you can also use the Reader.Read() and Writer.Write() methods to read and write slices of bytes. These will give you best performance ifthe underlying io.Reader and io.Writer are aligned to a byte boundary (else all the individual bytes are assembled from / spread to multiple bytes). You can ensure byte boundary by calling the Align() method of Reader and Writer.

Bit order

The more general highest-bits-first order is used. So for example if the input provides the bytes 0x8f and 0x55:

HEXA    8    f     5    5
BINARY  1100 1111  0101 0101
        aaaa bbbc  ccdd dddd

Then ReadBits will return the following values:

r := NewReader(bytes.NewBuffer([]byte{0x8f, 0x55}))
a, err := r.ReadBits(4) //   1100 = 0x08
b, err := r.ReadBits(3) //    111 = 0x07
c, err := r.ReadBits(3) //    101 = 0x05
d, err := r.ReadBits(6) // 010101 = 0x15

Writing the above values would result in the same sequence of bytes:

b := &bytes.Buffer{}
w := NewWriter(b)
err := w.WriteBits(0x08, 4)
err = w.WriteBits(0x07, 3)
err = w.WriteBits(0x05, 3)
err = w.WriteBits(0x15, 6)
err = w.Close()
// b will hold the bytes: 0x8f and 0x55

Index

• type Reader
  • func NewReader(p []byte) *Reader
  • func (r *Reader) Align() (skipped byte)
  • func (r *Reader) ReadBits(n byte) (u uint64, err error)
  • func (r *Reader) ReadBool() (b bool, err error)
  • func (r *Reader) ReadByte() (b byte, err error)
• type Writer
  • func NewWriter(out io.Writer) Writer

Types

type Reader

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

reader is the bit reader implementation.

func NewReader

func NewReader(p []byte) *Reader

NewReader returns a new Reader using the specified byte slice as the input (source).

func (*Reader) Align

func (r *Reader) Align() (skipped byte)

func (*Reader) ReadBits

func (r *Reader) ReadBits(n byte) (u uint64, err error)

func (*Reader) ReadBool

func (r *Reader) ReadBool() (b bool, err error)

func (*Reader) ReadByte

func (r *Reader) ReadByte() (b byte, err error)

ReadByte implements io.ByteReader.

type Writer

type Writer interface {
	// Writer is an io.Writer and io.Closer.
	// Close closes the bit writer, writes out cached bits.
	// If the underlying io.Writer implements io.Closer,
	// it will be closed after writing out cached bits.
	io.WriteCloser

	// Writer is also an io.ByteWriter.
	// WriteByte writes 8 bits.
	io.ByteWriter

	// WriteBits writes out the n lowest bits of r.
	// r cannot have bits set at positions higher than n-1 (zero indexed).
	WriteBits(r uint64, n byte) (err error)

	// WriteBool writes one bit: 1 if param is true, 0 otherwise.
	WriteBool(b bool) (err error)

	// Align aligns the bit stream to a byte boundary,
	// so next write will start/go into a new byte.
	// If there are cached bits, they are first written to the output.
	// Returns the number of skipped (unset but still written) bits.
	Align() (skipped byte, err error)
}

Writer is the bit writer interface. Must be closed in order to flush cached data. If you can't or don't want to close it, flushing data can also be forced by calling Align().

func NewWriter

func NewWriter(out io.Writer) Writer

NewWriter returns a new Writer using the specified io.Writer as the output.