package binary
import "encoding/binary"
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 google.golang.org/protobuf for protocol buffers.
Index ¶
- Constants
- Variables
- func Append(buf []byte, order ByteOrder, data any) ([]byte, error)
- func AppendUvarint(buf []byte, x uint64) []byte
- func AppendVarint(buf []byte, x int64) []byte
- func Decode(buf []byte, order ByteOrder, data any) (int, error)
- func Encode(buf []byte, order ByteOrder, data any) (int, error)
- func PutUvarint(buf []byte, x uint64) int
- func PutVarint(buf []byte, x int64) int
- func Read(r io.Reader, order ByteOrder, data any) error
- func ReadUvarint(r io.ByteReader) (uint64, error)
- func ReadVarint(r io.ByteReader) (int64, error)
- func Size(v any) int
- func Uvarint(buf []byte) (uint64, int)
- func Varint(buf []byte) (int64, int)
- func Write(w io.Writer, order ByteOrder, data any) error
- type AppendByteOrder
- type ByteOrder
Examples ¶
- ByteOrder (Get)
- ByteOrder (Put)
- PutUvarint
- PutVarint
- Read
- Read (Multi)
- Uvarint
- Varint
- 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 bigEndian
BigEndian is the big-endian implementation of ByteOrder and AppendByteOrder.
var LittleEndian littleEndian
LittleEndian is the little-endian implementation of ByteOrder and AppendByteOrder.
var NativeEndian nativeEndian
NativeEndian is the native-endian implementation of ByteOrder and AppendByteOrder.
Functions ¶
func Append ¶
Append appends the binary representation of data to buf. buf may be nil, in which case a new buffer will be allocated. See Write on which data are acceptable. It returns the (possibily extended) buffer containing data or an error.
func AppendUvarint ¶
AppendUvarint appends the varint-encoded form of x, as generated by PutUvarint, to buf and returns the extended buffer.
func AppendVarint ¶
AppendVarint appends the varint-encoded form of x, as generated by PutVarint, to buf and returns the extended buffer.
func Decode ¶
Decode decodes binary data from buf into data according to the given byte order. It returns an error if buf is too small, otherwise the number of bytes consumed from buf.
func Encode ¶
Encode encodes the binary representation of data into buf according to the given byte order. It returns an error if buf is too small, otherwise the number of bytes written into buf.
func PutUvarint ¶
PutUvarint encodes a uint64 into buf and returns the number of bytes written. If the buffer is too small, PutUvarint will panic.
func PutVarint ¶
PutVarint encodes an int64 into buf and returns the number of bytes written. If the buffer is too small, PutVarint will panic.
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 io.EOF only if no bytes were read.
If an io.EOF happens after reading some but not all the bytes,
Read returns io.ErrUnexpectedEOF.
Code:play
Output: Code:play
Output: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.NewReader(b)
err := binary.Read(buf, binary.LittleEndian, &pi)
if err != nil {
fmt.Println("binary.Read failed:", err)
}
fmt.Print(pi)
}
3.141592653589793
Example (Multi)¶
package main
import (
"bytes"
"encoding/binary"
"fmt"
)
func main() {
b := []byte{0x18, 0x2d, 0x44, 0x54, 0xfb, 0x21, 0x09, 0x40, 0xff, 0x01, 0x02, 0x03, 0xbe, 0xef}
r := bytes.NewReader(b)
var data struct {
PI float64
Uate uint8
Mine [3]byte
Too uint16
}
if err := binary.Read(r, binary.LittleEndian, &data); err != nil {
fmt.Println("binary.Read failed:", err)
}
fmt.Println(data.PI)
fmt.Println(data.Uate)
fmt.Printf("% x\n", data.Mine)
fmt.Println(data.Too)
}
3.141592653589793
255
01 02 03
61374
func ReadUvarint ¶
func ReadUvarint(r io.ByteReader) (uint64, error)
ReadUvarint reads an encoded unsigned integer from r and returns it as a uint64. The error is io.EOF only if no bytes were read. If an io.EOF happens after reading some but not all the bytes, ReadUvarint returns io.ErrUnexpectedEOF.
func ReadVarint ¶
func ReadVarint(r io.ByteReader) (int64, error)
ReadVarint reads an encoded signed integer from r and returns it as an int64. The error is io.EOF only if no bytes were read. If an io.EOF happens after reading some but not all the bytes, ReadVarint returns io.ErrUnexpectedEOF.
func Size ¶
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 Uvarint ¶
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.
Example¶
Code:play
package main import ( "encoding/binary" "fmt" ) func main() { inputs := [][]byte{ {0x01}, {0x02}, {0x7f}, {0x80, 0x01}, {0xff, 0x01}, {0x80, 0x02}, } for _, b := range inputs { x, n := binary.Uvarint(b) if n != len(b) { fmt.Println("Uvarint did not consume all of in") } fmt.Println(x) } }
Output:
1 2 127 128 255 256
func Varint ¶
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.
Example¶
Code:play
package main import ( "encoding/binary" "fmt" ) func main() { inputs := [][]byte{ {0x81, 0x01}, {0x7f}, {0x03}, {0x01}, {0x00}, {0x02}, {0x04}, {0x7e}, {0x80, 0x01}, } for _, b := range inputs { x, n := binary.Varint(b) if n != len(b) { fmt.Println("Varint did not consume all of in") } fmt.Println(x) } }
Output:
-65 -64 -2 -1 0 1 2 63 64
func Write ¶
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.
Code:play
Output: Code:play
Output: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())
}
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 = []any{
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())
}
beefcafe
Types ¶
type AppendByteOrder ¶
type AppendByteOrder interface { AppendUint16([]byte, uint16) []byte AppendUint32([]byte, uint32) []byte AppendUint64([]byte, uint64) []byte String() string }
AppendByteOrder specifies how to append 16-, 32-, or 64-bit unsigned integers into a byte slice.
It is implemented by LittleEndian, BigEndian, and NativeEndian.
type ByteOrder ¶
type ByteOrder interface { Uint16([]byte) uint16 Uint32([]byte) uint32 Uint64([]byte) uint64 PutUint16([]byte, uint16) PutUint32([]byte, uint32) PutUint64([]byte, uint64) String() string }
A ByteOrder specifies how to convert byte slices into 16-, 32-, or 64-bit unsigned integers.
It is implemented by LittleEndian, BigEndian, and NativeEndian.
Source Files ¶
binary.go native_endian_little.go varint.go
- Version
- v1.23.2 (latest)
- Published
- Sep 28, 2024
- Platform
- linux/amd64
- Imports
- 6 packages
- Last checked
- 30 minutes ago –
Tools for package owners.