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
- 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 是 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。
Output: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])
}
}
01
02
7f
8001
ff01
8002
func PutVarint
func PutVarint(buf []byte, x int64) int
PutVarint 将 int64 编码到 buf 并返回写入的字节数。
如果缓冲区太小,PutVarint 会 panic。
Output: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])
}
}
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。
Output: 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 从 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,含义为:
- n == 0:buf 太小;
- n < 0:值大于 64 位(溢出),且 -n 为读取的字节数。
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,含义如下:
- n == 0:buf 太小;
- n < 0:值大于 64 位(溢出), 且 -n 为读取的字节数。
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 的各个连续字段读取。
写入结构体时,字段名为空白(_)的字段会写入零值。
Output: 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 指定如何将 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 实现。
Output: Output: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)
}
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)
}
e8 03 d0 07