binary

Documentation

Overview

Package binary implements simple translation between numbers and byte sequences and encoding and decoding of varints.

It's a drop in replacement for encoding/binary in the standard library but offers very significant increases in performance. This package is typically 6x-7x faster than encoding/binary. This difference is even bigger when using small data types (like int8 and uint8), in those cases performance is around 350x-450x faster.

Numbers are translated by reading and writing fixed-size values. A fixed-size value is either a fixed-size arithmetic type (int8, uint8, int16, float32, complex64, ...) or an array or struct containing only fixed-size values.

Varints are a method of encoding integers using one or more bytes; numbers with smaller absolute value take a smaller number of bytes. For a specification, see http://code.google.com/apis/protocolbuffers/docs/encoding.html.

Index

• Constants
• Variables
• func PutUvarint(buf []byte, x uint64) int
• func PutVarint(buf []byte, x int64) int
• func Read(r io.Reader, order *ByteOrder, data interface{}) error
• func ReadUvarint(r io.ByteReader) (uint64, error)
• func ReadVarint(r io.ByteReader) (int64, error)
• func Size(v interface{}) int
• func Uvarint(buf []byte) (uint64, int)
• func Varint(buf []byte) (int64, int)
• func Write(w io.Writer, order *ByteOrder, data interface{}) error
• type ByteOrder
  • func (b *ByteOrder) GoString() string
  • func (b *ByteOrder) String() string

Examples

• Read
• Write
• Write (Multi)

Constants

const (
	MaxVarintLen16 = 3
	MaxVarintLen32 = 5
	MaxVarintLen64 = 10
)

MaxVarintLenN is the maximum length of a varint-encoded N-bit integer.

Variables

var BigEndian = &ByteOrder{
	Uint16:    beUint16,
	Uint32:    beUint32,
	Uint64:    beUint64,
	PutUint16: bePutUint16,
	PutUint32: bePutUint32,
	PutUint64: bePutUint64,
	name:      "BigEndian",
}

BigEndian is the big-endian implementation of ByteOrder.

var LittleEndian = &ByteOrder{
	Uint16:    leUint16,
	Uint32:    leUint32,
	Uint64:    leUint64,
	PutUint16: lePutUint16,
	PutUint32: lePutUint32,
	PutUint64: lePutUint64,
	name:      "LittleEndian",
}

LittleEndian is the little-endian implementation of ByteOrder.

Functions

func PutUvarint

func PutUvarint(buf []byte, x uint64) int

PutUvarint encodes a uint64 into buf and returns the number of bytes written. If the buffer is too small, PutUvarint will panic.

func PutVarint

func PutVarint(buf []byte, x int64) int

PutVarint encodes an int64 into buf and returns the number of bytes written. If the buffer is too small, PutVarint will panic.

func Read

func Read(r io.Reader, order *ByteOrder, data interface{}) error

Read reads structured binary data from r into data. Data must be a pointer to a fixed-size value or a slice of fixed-size values. Bytes read from r are decoded using the specified byte order and written to successive fields of the data. When reading into structs, the field data for fields with blank (_) field names is skipped; i.e., blank field names may be used for padding.

Example

package main

import (
	"bytes"
	"encoding/binary"
	"fmt"
)

func main() {
	var pi float64
	b := []byte{0x18, 0x2d, 0x44, 0x54, 0xfb, 0x21, 0x09, 0x40}
	buf := bytes.NewBuffer(b)
	err := binary.Read(buf, binary.LittleEndian, &pi)
	if err != nil {
		fmt.Println("binary.Read failed:", err)
	}
	fmt.Print(pi)
}

Output:

3.141592653589793

func ReadUvarint

func ReadUvarint(r io.ByteReader) (uint64, error)

ReadUvarint reads an encoded unsigned integer from r and returns it as a uint64.

func ReadVarint

func ReadVarint(r io.ByteReader) (int64, error)

ReadVarint reads an encoded signed integer from r and returns it as an int64.

func Size

func Size(v interface{}) int

Size returns how many bytes Write would generate to encode the value v, which must be a fixed-size value or a slice of fixed-size values, or a pointer to such data.

func Uvarint

func Uvarint(buf []byte) (uint64, int)

Uvarint decodes a uint64 from buf and returns that value and the number of bytes read (> 0). If an error occurred, the value is 0 and the number of bytes n is <= 0 meaning:

	n == 0: buf too small
	n  < 0: value larger than 64 bits (overflow)
             and -n is the number of bytes read

func Varint

func Varint(buf []byte) (int64, int)

Varint decodes an int64 from buf and returns that value and the number of bytes read (> 0). If an error occurred, the value is 0 and the number of bytes n is <= 0 with the following meaning:

	n == 0: buf too small
	n  < 0: value larger than 64 bits (overflow)
             and -n is the number of bytes read

func Write

func Write(w io.Writer, order *ByteOrder, data interface{}) error

Write writes the binary representation of data into w. Data must be a fixed-size value or a slice of fixed-size values, or a pointer to such data. Bytes written to w are encoded using the specified byte order and read from successive fields of the data. When writing structs, zero values are written for fields with blank (_) field names.

Example

package main

import (
	"bytes"
	"encoding/binary"
	"fmt"
	"math"
)

func main() {
	buf := new(bytes.Buffer)
	var pi float64 = math.Pi
	err := binary.Write(buf, binary.LittleEndian, pi)
	if err != nil {
		fmt.Println("binary.Write failed:", err)
	}
	fmt.Printf("% x", buf.Bytes())
}

Output:

18 2d 44 54 fb 21 09 40

Example (Multi)

package main

import (
	"bytes"
	"encoding/binary"
	"fmt"
)

func main() {
	buf := new(bytes.Buffer)
	var data = []interface{}{
		uint16(61374),
		int8(-54),
		uint8(254),
	}
	for _, v := range data {
		err := binary.Write(buf, binary.LittleEndian, v)
		if err != nil {
			fmt.Println("binary.Write failed:", err)
		}
	}
	fmt.Printf("%x", buf.Bytes())
}

Output:

beefcafe

Types

type ByteOrder

type ByteOrder struct {
	Uint16    func([]byte) uint16
	Uint32    func([]byte) uint32
	Uint64    func([]byte) uint64
	PutUint16 func([]byte, uint16)
	PutUint32 func([]byte, uint32)
	PutUint64 func([]byte, uint64)
	// contains filtered or unexported fields
}

A ByteOrder specifies how to convert byte sequences into 16-, 32-, or 64-bit unsigned integers.

func (*ByteOrder) GoString

func (b *ByteOrder) GoString() string

func (*ByteOrder) String

func (b *ByteOrder) String() string