bit

README

bit

This package provides Encode/Decode functionality for byte sequences into bit strings.
For example, a byte represented by the hexadecimal number ff would be encoded as 1111111111 .

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

Why is this necessary?

Go does not (as far as I can tell) have the flexibility to output raw byte sequences as bit strings.
This can be a problem in log output when, for example, parsing a binary message fails.

Bit output with padding like fmt.Sprintf("%08b", buf) is close,
but 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 the package documentation.

Encode

Encode the given byte sequence.

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

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

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

// Output:
// 01001000011001010110110001101100011011110010000001000111011011110111000001101000011001010111001000100001

Decode

The input to the decoding process is a bit-encoded byte sequence.
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 the same output as 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 an odd-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