bitreader

README

bitreader

Provides basic interfaces to read and traverse an io.Reader as a stream of bits, rather than a stream of bytes.

Installation

$ go get github.com/32bitkid/bitreader

Examples

Ever wanted to count the number of 0 bits from the start of a file?

package main

import (
	"os"
	"fmt"
	"github.com/32bitkid/bitreader"
)

func main() {
    file, _ := os.Open("file")
    r := bitreader.NewReader(file)
    n := 0
    for {
        val, err := r.Read1()
        if err != nil || val == true {
            break
        }
        n += 1
    }
    fmt.Printf("The file starts with %d off bits", n)
}

But seriously, this is used for parsing densely packed binary formats where data may not be byte aligned. For example, decoding values packed with Huffman Coding.

Documentation

Overview

Package bitreader provides basic interfaces to read and traverse an io.Reader as a stream of bits, rather than a stream of bytes.

Index

• type Aligner
• type BitReader
  • func NewReader(r io.Reader) BitReader
• type BitReader1
• type BitReader16
• type BitReader32
• type BitReader8
• type Peeker
• type Peeker16
• type Peeker32
• type Peeker64
• type Peeker8
• type Reader
• type Reader16
• type Reader32
• type Reader64
• type Reader8
• type Skipper

Types

type Aligner

type Aligner interface {
	IsAligned() bool
	Align() (n uint, err error)
}

Aligner is the interface that allows for byte realignment.

IsAligned() returns true if the bit stream is currently aligned to a byte boundary.

Align() will skip the necessary bit to realign the bit stream to a byte boundary. It returns the number of bits skipped (0 <= n < 8) during realignment.

type BitReader

type BitReader interface {
	io.Reader

	Reader64
	Peeker64
	Skipper
	Aligner
}

func NewReader

func NewReader(r io.Reader) BitReader

NewBitReader returns the default implementation of a BitReader

type BitReader1

type BitReader1 interface {
	io.Reader

	Reader
	Peeker
	Skipper
	Aligner
}

type BitReader16

type BitReader16 interface {
	io.Reader

	Reader16
	Peeker16
	Skipper
	Aligner
}

type BitReader32

type BitReader32 interface {
	io.Reader

	Reader32
	Peeker32
	Skipper
	Aligner
}

type BitReader8

type BitReader8 interface {
	io.Reader

	Reader8
	Peeker8
	Skipper
	Aligner
}

type Peeker

type Peeker interface {
	Peek1() (bool, error)
}

Peeker is the interface that wraps the basic Peek1 method

Peek1 will return true or false depending on whether or not the next bit in the bit stream is set; it does not advance the stream any bits.

type Peeker16

type Peeker16 interface {
	Peeker8
	Peek16(n uint) (uint16, error)
}

type Peeker32

type Peeker32 interface {
	Peeker16
	Peek32(n uint) (uint32, error)
}

Peeker32 is the interface that wraps the basic Peek32 method.

Peek32 allows for reading multiple bits, where (1 <= n <= 32) as a uint32 from the bit stream; it does not advance the bit stream any bits.

type Peeker64

type Peeker64 interface {
	Peeker32
	Peek64(n uint) (uint64, error)
}

type Peeker8

type Peeker8 interface {
	Peeker
	Peek8(n uint) (uint8, error)
}

type Reader

type Reader interface {
	Read1() (bool, error)
}

Reader1 is the interface that wraps the basic Read1 method

Read1() will return true or false depending on whether or not the next bit in the bit stream is set, then advance one bit forward in the bit-stream.

Read1() is the equivalent to Peek1() followed by Skip(1)

type Reader16

type Reader16 interface {
	Reader8
	Read16(n uint) (uint16, error)
}

type Reader32

type Reader32 interface {
	Reader16
	Read32(n uint) (uint32, error)
}

Reader32 is the interface that wraps the basic Read32 method.

Read32 allows for reading multiple bits, where (1 <= n <= 32) as a uint32 from the bit stream. Then advancing the bit stream by n bits.

Read32(n) is equivalent to Peek32(n) followed by Skip(n)

type Reader64

type Reader64 interface {
	Reader32
	Read64(n uint) (uint64, error)
}

type Reader8

type Reader8 interface {
	Reader
	Read8(n uint) (uint8, error)
}

type Skipper

type Skipper interface {
	Skip(n uint) error
}

Skipper is the interface that wraps the basic Skip method.

Skip will advance the bit stream by n bits. Note, n is not constrained, like PeekX and ReadX methods. You can skip any number of bits up to max uint; the reader will continue to fill and drain the buffer until complete.