Repository files navigation

Packagebitio provides an optimized bit-levelReader andWriter for Go.

You can useReader.ReadBits() to read arbitrary number of bits from anio.Reader and return it as anuint64,andWriter.WriteBits() to write arbitrary number of bits of anuint64 value to anio.Writer.

BothReader andWriter also provide optimized methods for reading / writing1 bit of information in the form of abool value:Reader.ReadBool() andWriter.WriteBool().These make this package ideal for compression algorithms that useHuffman coding for example,where decision whether to step left or right in the Huffman tree is the most frequent operation.

Reader andWriter give abit-level view of the underlyingio.Reader andio.Writer, but they alsoprovide abyte-level view (io.Reader andio.Writer) at the same time. This means you can also usetheReader.Read() andWriter.Write() methods to read and write slices of bytes. These will giveyou best performance if the underlyingio.Reader andio.Writer are aligned to a byte boundary(else all the individual bytes are assembled from / spread to multiple bytes). You can ensurebyte boundary alignment by calling theAlign() method ofReader andWriter. As an extra,io.ByteReader andio.ByteWriter are also implemented.

The more general highest-bits-first order is used. So for example if the input provides the bytes0x8f and0x55:

HEXA    8    f     5    5BINARY  1000 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)//   1000 = 0x08b,err:=r.ReadBits(3)//    111 = 0x07c,err:=r.ReadBits(3)//    101 = 0x05d,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

AllReadXXX() andWriteXXX() methods return an error which you are expected to handle.For convenience, there are also matchingTryReadXXX() andTryWriteXXX() methodswhich do not return an error. Instead they store the (first) error in theReader.TryError /Writer.TryError field which you can inspect later.TheseTryXXX() methods are a no-op if aTryError has been encountered before,so it's safe to call multipleTryXXX() methods and defer the error checking.

For example:

r:=NewReader(bytes.NewBuffer([]byte{0x8f,0x55}))a:=r.TryReadBits(4)//   1000 = 0x08b:=r.TryReadBits(3)//    111 = 0x07c:=r.TryReadBits(3)//    101 = 0x05d:=r.TryReadBits(6)// 010101 = 0x15ifr.TryError!=nil {// Handle error}

This allows you to easily convert the result of individualReadBits(), like this:

r:=NewReader(bytes.NewBuffer([]byte{0x8f,0x55}))a:=byte(r.TryReadBits(4))//   1000 = 0x08b:=int32(r.TryReadBits(3))//    111 = 0x07c:=int64(r.TryReadBits(3))//    101 = 0x05d:=uint16(r.TryReadBits(6))// 010101 = 0x15ifr.TryError!=nil {// Handle error}

And similarly:

b:=&bytes.Buffer{}w:=NewWriter(b)w.TryWriteBits(0x08,4)w.TryWriteBits(0x07,3)w.TryWriteBits(0x05,3)w.TryWriteBits(0x15,6)ifw.TryError!=nil {// Handle error}err=w.Close()// b will hold the bytes: 0x8f and 0x55

For performance reasons,Reader andWriter do not keep track of the number of read or written bits.If you happen to need the total number of processed bits, you may use theCountReader andCountWriter typeswhich have identical API to that ofReader andWriter, but they also maintain the number of processed bitswhich you can query using theBitsCount field.

Licensed under either of

• Apache License, Version 2.0
• GNU LESSER GENERAL PUBLIC LICENSE, Version 2.1

at your option.