package binary

import "encoding/binary"

Package binary 实现了数字与字节序列之间的简单转换,以及 varint 的编码和解码。

数字通过读取和写入固定大小的值进行转换。 固定大小的值可以是固定大小的算术类型(bool、int8、uint8、int16、 float32、complex64 等),也可以是仅包含固定大小值的数组或结构体。

varint 函数使用变长编码对单个整数值进行编码和解码;较小的值需要更少的字节。 有关规范,请参见 https://developers.google.com/protocol-buffers/docs/encoding。

本包更注重简洁性而非效率。需要高性能序列化(尤其是对于大型数据结构)的客户端 应研究更高级的解决方案,例如 encoding/gob 包, 或用于 protocol buffers 的 google.golang.org/protobuf。

Index

Examples

Constants

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

MaxVarintLenN 是 varint 编码的 N 位整数的最大长度。

Variables

var BigEndian bigEndian

BigEndian 是 ByteOrder 和 AppendByteOrder 的大端字节序实现。

var LittleEndian littleEndian

LittleEndian 是 ByteOrder 和 AppendByteOrder 的小端字节序实现。

var NativeEndian nativeEndian

NativeEndian 是 ByteOrder 和 AppendByteOrder 的本机字节序实现。

Functions

func Append

func Append(buf []byte, order ByteOrder, data any) ([]byte, error)

Append 将 data 的二进制表示追加到 buf。 buf 可以为 nil,此时会分配一个新的缓冲区。 关于哪些 data 是可接受的,请参见 Write。 它返回包含 data 的(可能已扩展的)缓冲区,或返回错误。

func AppendUvarint

func AppendUvarint(buf []byte, x uint64) []byte

AppendUvarint 将 x 的 varint 编码形式(由 PutUvarint 生成) 追加到 buf 并返回扩展后的缓冲区。

func AppendVarint

func AppendVarint(buf []byte, x int64) []byte

AppendVarint 将 x 的 varint 编码形式(由 PutVarint 生成) 追加到 buf 并返回扩展后的缓冲区。

func Decode

func Decode(buf []byte, order ByteOrder, data any) (int, error)

Decode 按给定的字节序将 buf 中的二进制数据解码到 data。 如果 buf 太小,它会返回错误,否则返回从 buf 消耗的字节数。

func Encode

func Encode(buf []byte, order ByteOrder, data any) (int, error)

Encode 按给定的字节序将 data 的二进制表示编码到 buf。 如果 buf 太小,它会返回错误,否则返回写入 buf 的字节数。

func PutUvarint

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

PutUvarint 将 uint64 编码到 buf 并返回写入的字节数。 如果缓冲区太小,PutUvarint 会 panic。

Example
package main

import (
	"encoding/binary"
	"fmt"
)

func main() {
	buf := make([]byte, binary.MaxVarintLen64)

	for _, x := range []uint64{1, 2, 127, 128, 255, 256} {
		n := binary.PutUvarint(buf, x)
		fmt.Printf("%x\n", buf[:n])
	}
}

Output:

01
02
7f
8001
ff01
8002

func PutVarint

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

PutVarint 将 int64 编码到 buf 并返回写入的字节数。 如果缓冲区太小,PutVarint 会 panic。

Example
package main

import (
	"encoding/binary"
	"fmt"
)

func main() {
	buf := make([]byte, binary.MaxVarintLen64)

	for _, x := range []int64{-65, -64, -2, -1, 0, 1, 2, 63, 64} {
		n := binary.PutVarint(buf, x)
		fmt.Printf("%x\n", buf[:n])
	}
}

Output:

8101
7f
03
01
00
02
04
7e
8001

func Read

func Read(r io.Reader, order ByteOrder, data any) error

Read 从 r 读取结构化二进制数据并存入 data。 data 必须是指向固定大小值的指针,或者是固定大小值的切片。 从 r 读取的字节按指定的字节序解码,并写入 data 的各个连续字段。 解码布尔值时,零字节被解码为 false,任何其他非零字节被解码为 true。 读入结构体时,字段名为空白(_)的字段数据会被跳过; 也就是说,空白字段名可用于填充。 读入结构体时,所有非空白字段都必须导出,否则 Read 可能会 panic。

只有在未读取任何字节时,错误才为 io.EOF。 如果在读取了一些但并非全部字节之后发生 io.EOF, Read 会返回 io.ErrUnexpectedEOF。

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)
}

Output:

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)
}

Output:

3.141592653589793
255
01 02 03
61374

func ReadUvarint

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

ReadUvarint 从 r 读取一个编码的无符号整数并以 uint64 返回。 只有在未读取任何字节时,错误才为 io.EOF。 如果在读取了一些但并非全部字节之后发生 io.EOF, ReadUvarint 会返回 io.ErrUnexpectedEOF。

func ReadVarint

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

ReadVarint 从 r 读取一个编码的有符号整数并以 int64 返回。 只有在未读取任何字节时,错误才为 io.EOF。 如果在读取了一些但并非全部字节之后发生 io.EOF, ReadVarint 会返回 io.ErrUnexpectedEOF。

func Size

func Size(v any) int

Size 返回 Write 为编码值 v 会生成多少字节,v 必须是固定大小值、固定大小值的切片,或指向此类数据的指针。 如果 v 不属于这些类型,Size 返回 -1。

func Uvarint

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

Uvarint 从 buf 解码一个 uint64 并返回该值以及读取的字节数(> 0)。 如果发生错误,值为 0,且字节数 n <= 0,含义为:

Example
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

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

Varint 从 buf 解码一个 int64 并返回该值以及读取的字节数(> 0)。 如果发生错误,值为 0,且字节数 n <= 0,含义如下:

Example
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

func Write(w io.Writer, order ByteOrder, data any) error

Write 将 data 的二进制表示写入 w。 data 必须是固定大小值、固定大小值的切片,或指向此类数据的指针。 布尔值编码为一个字节:true 为 1,false 为 0。 写入 w 的字节按指定的字节序编码,并从 data 的各个连续字段读取。 写入结构体时,字段名为空白(_)的字段会写入零值。

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 = []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())
}

Output:

beefcafe

Types

type AppendByteOrder

type AppendByteOrder interface {
	AppendUint16([]byte, uint16) []byte
	AppendUint32([]byte, uint32) []byte
	AppendUint64([]byte, uint64) []byte
	String() string
}

AppendByteOrder 指定如何将 16 位、32 位或 64 位无符号整数 追加到字节切片中。

它由 LittleEndian、BigEndian 和 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
}

ByteOrder 指定如何将字节切片转换为 16 位、32 位或 64 位无符号整数。

它由 LittleEndian、BigEndian 和 NativeEndian 实现。

Example (Get)
package main

import (
	"encoding/binary"
	"fmt"
)

func main() {
	b := []byte{0xe8, 0x03, 0xd0, 0x07}
	x1 := binary.LittleEndian.Uint16(b[0:])
	x2 := binary.LittleEndian.Uint16(b[2:])
	fmt.Printf("%#04x %#04x\n", x1, x2)
}

Output:

0x03e8 0x07d0
Example (Put)
package main

import (
	"encoding/binary"
	"fmt"
)

func main() {
	b := make([]byte, 4)
	binary.LittleEndian.PutUint16(b[0:], 0x03e8)
	binary.LittleEndian.PutUint16(b[2:], 0x07d0)
	fmt.Printf("% x\n", b)
}

Output:

e8 03 d0 07