Overview

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

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

The varint functions encode and decode single integer values using a
variable-length encoding; smaller values require fewer bytes. For a
specification, see https://developers.google.com/protocol-buffers/docs/encoding.

This package favors simplicity over efficiency. Clients that require
high-performance serialization, especially for large data structures, should
look at more advanced solutions such as the encoding/gob package or protocol
buffers.

Index

Package files

varint.go

Constants

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

Variables

  1. var BigEndian bigEndian

BigEndian is the big-endian implementation of ByteOrder.

  1. var LittleEndian littleEndian

LittleEndian is the little-endian implementation of ByteOrder.

  1. func PutUvarint(buf [], x uint64)

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


Example:

  1. buf := make([]byte, binary.MaxVarintLen64)
  2. for _, x := range []uint64{1, 2, 127, 128, 255, 256} {
  3. n := binary.PutUvarint(buf, x)
  4. fmt.Printf("%x\n", buf[:n])
  5. }
  6. // Output:
  7. // 01
  8. // 02
  9. // 7f
  10. // 8001
  11. // ff01
  12. // 8002

func

  1. func PutVarint(buf [], x int64)

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

  1. buf := make([]byte, binary.MaxVarintLen64)
  2. for _, x := range []int64{-65, -64, -2, -1, 0, 1, 2, 63, 64} {
  3. n := binary.PutVarint(buf, x)
  4. fmt.Printf("%x\n", buf[:n])
  5. }
  6. // Output:
  7. // 8101
  8. // 7f
  9. // 03
  10. // 01
  11. // 00
  12. // 02
  13. // 04
  14. // 7e
  15. // 8001

func Read

    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 decoding boolean values, a zero byte is decoded as false, and any other
    non-zero byte is decoded as true. 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. When reading into a struct, all non-blank fields must be
    exported or Read may panic.

    The error is EOF only if no bytes were read. If an EOF happens after reading
    some but not all the bytes, Read returns ErrUnexpectedEOF.


    Example:


    Example:

    1. b := []byte{0x18, 0x2d, 0x44, 0x54, 0xfb, 0x21, 0x09, 0x40, 0xff, 0x01, 0x02, 0x03, 0xbe, 0xef}
    2. r := bytes.NewReader(b)
    3. var data struct {
    4. PI float64
    5. Uate uint8
    6. Mine [3]byte
    7. Too uint16
    8. }
    9. if err := binary.Read(r, binary.LittleEndian, &data); err != nil {
    10. fmt.Println("binary.Read failed:", err)
    11. }
    12. fmt.Println(data.PI)
    13. fmt.Printf("% x\n", data.Mine)
    14. fmt.Println(data.Too)
    15. // Output:
    16. // 3.141592653589793
    17. // 255
    18. // 01 02 03
    19. // 61374

    func ReadUvarint

    1. func ReadUvarint(r io.) (uint64, )

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

    func ReadVarint

    1. func ReadVarint(r io.) (int64, )

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

    1. 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. If v is neither of these, Size returns -1.

    func

    1. func Uvarint(buf []) (uint64, )

    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:

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


    Example:

    1. inputs := [][]byte{
    2. []byte{0x01},
    3. []byte{0x02},
    4. []byte{0x7f},
    5. []byte{0x80, 0x01},
    6. []byte{0xff, 0x01},
    7. []byte{0x80, 0x02},
    8. }
    9. for _, b := range inputs {
    10. x, n := binary.Uvarint(b)
    11. if n != len(b) {
    12. fmt.Println("Uvarint did not consume all of in")
    13. }
    14. fmt.Println(x)
    15. }
    16. // Output:
    17. // 1
    18. // 2
    19. // 127
    20. // 128
    21. // 255
    22. // 256

    func

    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:

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


    Example:

    1. inputs := [][]byte{
    2. []byte{0x81, 0x01},
    3. []byte{0x7f},
    4. []byte{0x03},
    5. []byte{0x00},
    6. []byte{0x02},
    7. []byte{0x04},
    8. []byte{0x7e},
    9. }
    10. for _, b := range inputs {
    11. x, n := binary.Varint(b)
    12. if n != len(b) {
    13. fmt.Println("Varint did not consume all of in")
    14. }
    15. fmt.Println(x)
    16. }
    17. // Output:
    18. // -65
    19. // -64
    20. // -2
    21. // -1
    22. // 0
    23. // 1
    24. // 2
    25. // 63
    26. // 64

    func Write

    1. func Write(w io., order ByteOrder, data interface{})

    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. Boolean values
    encode as one byte: 1 for true, and 0 for false. 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:

    1. buf := new(bytes.Buffer)
    2. var pi float64 = math.Pi
    3. err := binary.Write(buf, binary.LittleEndian, pi)
    4. if err != nil {
    5. fmt.Println("binary.Write failed:", err)
    6. }
    7. fmt.Printf("% x", buf.Bytes())
    8. // Output: 18 2d 44 54 fb 21 09 40


    Example:

    1. buf := new(bytes.Buffer)
    2. var data = []interface{}{
    3. uint16(61374),
    4. int8(-54),
    5. uint8(254),
    6. }
    7. for _, v := range data {
    8. err := binary.Write(buf, binary.LittleEndian, v)
    9. if err != nil {
    10. fmt.Println("binary.Write failed:", err)
    11. }
    12. }
    13. fmt.Printf("%x", buf.Bytes())
    14. // Output: beefcafe

    type ByteOrder

    1. type ByteOrder interface {
    2. Uint16([]byte)
    3. Uint32([]byte)
    4. Uint64([]byte)
    5. PutUint16([]byte, )
    6. PutUint32([]byte, )
    7. PutUint64([]byte, )
    8. String() string
    9. }

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


    Example:

    1. b := []byte{0xe8, 0x03, 0xd0, 0x07}
    2. x1 := binary.LittleEndian.Uint16(b[0:])
    3. x2 := binary.LittleEndian.Uint16(b[2:])
    4. fmt.Printf("%#04x %#04x\n", x1, x2)
    5. // 0x03e8 0x07d0


    Example: