bit

README

bit

This package provides encoding for converting byte sequences to bit strings.
For example, a byte represented by the hexadecimal number ff would be encoded as 11111111 .

Inspired by the standard package encoding/hex. I also got some implementation hints from it.

Why is this necessary?

Byte sequences can be output as bit strings using the standard package fmt as follows

for i := 0; i < len(src); i++ {
    fmt.Printf("%08b", src[i])
}

In some cases, this is sufficient. However, this does not implement io.Reader or io.Writer , so flexible handling such as stream support is not possible.
In addition, it is tedious to output in a human-readable format like xxd -b.

Therefore, outputting bit strings using the standard package fmt is inconvenient, for example, when debugging a program that evaluates binaries.

I created this package for more flexible handling (e.g. io.Reader and io.Writer support, Or Dump() output support like xxd -b ).

Usage

Here are the basics. If you want more details, please refer to example_test or package documentation.

Encode

Encode the given byte sequences.

src := []byte("Hello Gopher!")

dst := make([]byte, EncodedLen(len(src)))
Encode(dst, src)

fmt.Printf("%s\n", dst)

// Output:
// 01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001

Decode

Decode takes as input a bit-encoded byte sequences.
Eight characters represent one byte, so the input must be a multiple of 8 bytes.

src := []byte("01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001")

dst := make([]byte, DecodedLen(len(src)))
n, err := Decode(dst, src)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%s\n", dst[:n])

// Output:
// Hello Gopher!

Dump

Dump returns output like xxd -b .

dump := Dump([]byte("dump test"))
fmt.Printf("%s\n", dump)

// Output:
// 00000000: 01100100 01110101 01101101 01110000 00100000 01110100  dump t
// 00000006: 01100101 01110011 01110100                             est

LICENSE

MIT

Documentation

Overview

Package bit implements an encoding scheme in which one byte is represented by eight binary digits of 0 or 1.

It also provides a Dump() function to dump a sequence of bytes (similar to encoding/hex in the standard package).

Index

• Variables
• func Decode(dst, src []byte) (int, error)
• func DecodeString(s string) ([]byte, error)
• func DecodedLen(x int) int
• func Dump(data []byte) string
• func Dumper(w io.Writer) io.WriteCloser
• func Encode(dst, src []byte) int
• func EncodeToString(src []byte) string
• func EncodedLen(n int) int
• func NewDecoder(r io.Reader) io.Reader
• func NewEncoder(w io.Writer) io.Writer
• type InvalidByteError
  • func (e InvalidByteError) Error() string

Examples

• Decode
• DecodeString
• Dump
• Dumper
• Encode
• EncodeToString
• NewDecoder
• NewEncoder

Variables

var ErrLength = errors.New("bit: bit string length not a multiple of 8")

ErrLength reports an attempt to decode not a multiple of 8 length input using Decode or DecodeString. The stream-based Decoder returns io.ErrUnexpectedEOF instead of ErrLength.

Functions

func Decode

func Decode(dst, src []byte) (int, error)

Decode decodes src into DecodedLen(len(src)) bytes, returning the actual number of bytes written to dst.

Decode expects that src contains only '0' or '1' characters and that src has multiple of 8 length. If the input is malformed, Decode returns the number of bytes decoded before the error.

Example

src := []byte("01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001")

dst := make([]byte, DecodedLen(len(src)))
n, err := Decode(dst, src)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%s\n", dst[:n])

Output:

Hello Gopher!

func DecodeString

func DecodeString(s string) ([]byte, error)

DecodeString returns the bytes represented by the bit string s.

DecodeString expects that src contains only bit characters and that src has multiple of 8 length. If the input is malformed, DecodeString returns the bytes decoded before the error.

Example

const s = "01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001"
decoded, err := DecodeString(s)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("%s\n", decoded)

Output:

Hello Gopher!

func DecodedLen

func DecodedLen(x int) int

DecodedLen returns the length of a decoding of x source bytes. Specifically, it returns x / 8.

func Dump

func Dump(data []byte) string

Dump returns a string that contains a bit dump of the given data. The format of the bit dump matches the output of `xxd -b` on the command line.

Example

dump := Dump([]byte("dump test"))
fmt.Printf("%s\n", dump)

Output:

00000000: 01100100 01110101 01101101 01110000 00100000 01110100  dump t
00000006: 01100101 01110011 01110100                             est

func Dumper

func Dumper(w io.Writer) io.WriteCloser

Dumper returns a WriteCloser that writes a bit dump of all written data to w. The format of the dump matches the output of `xxd -b` on the command line.

Example

d := Dumper(os.Stdout)
d.Write([]byte("dump test"))
d.Close()

Output:

00000000: 01100100 01110101 01101101 01110000 00100000 01110100  dump t
00000006: 01100101 01110011 01110100                             est

func Encode

func Encode(dst, src []byte) int

Encode encodes src into EncodedLen(len(src)) bytes of dst. As a convenience, it returns the number of bytes written to dst, but this value is always EncodedLen(len(src)). Encode implements bit encoding.

Example

src := []byte("Hello Gopher!")

dst := make([]byte, EncodedLen(len(src)))
Encode(dst, src)

fmt.Printf("%s\n", dst)

Output:

01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001

func EncodeToString

func EncodeToString(src []byte) string

EncodeToString returns the bit encoding of src.

Example

src := []byte("Hello Gopher!")
encodedStr := EncodeToString(src)

fmt.Printf("%s\n", encodedStr)

Output:

01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001

func EncodedLen

func EncodedLen(n int) int

EncodedLen returns the length of an encoding of n source bytes. Specifically, it returns n * 8.

func NewDecoder

func NewDecoder(r io.Reader) io.Reader

NewDecoder returns an io.Reader that decodes bit characters from r. NewDecoder expects that r contain only an multiple of 8 length of bit characters.

Example

src := []byte("01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001")

buf := bytes.NewBuffer(src)
dec := NewDecoder(buf)

io.Copy(os.Stdout, dec)

Output:

Hello Gopher!

func NewEncoder

func NewEncoder(w io.Writer) io.Writer

NewEncoder returns an io.Writer that writes bit characters to w.

Example

src := []byte("Hello Gopher!")
enc := NewEncoder(os.Stdout)

enc.Write(src)

Output:

01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001

Types

type InvalidByteError

type InvalidByteError byte

InvalidByteError values describe errors resulting from an invalid byte in a bit string.

func (InvalidByteError) Error

func (e InvalidByteError) Error() string