# package binary `import "encoding/binary"` binary包实现了简单的数字与字节序列的转换以及变长值的编解码。 数字翻译为定长值来读写，一个定长值，要么是固定长度的数字类型（int8, uint8, int16, float32, complex64, ...）或者只包含定长值的结构体或者数组。 变长值是使用一到多个字节编码整数的方法，绝对值较小的数字会占用较少的字节数。详情请参见：[http://code.google.com/apis/protocolbuffers/docs/encoding.html](http://code.google.com/apis/protocolbuffers/docs/encoding.html)。 本包相对于效率更注重简单。如果需要高效的序列化，特别是数据结构较复杂的，请参见更高级的解决方法，例如encoding/gob包，或者采用协议缓存。 ## Index * [Constants](#pkg-constants) * [Variables](#pkg-variables) * [type ByteOrder](#ByteOrder) * [func Size(v interface{}) int](#Size) * [func Uvarint(buf []byte) (uint64, int)](#Uvarint) * [func Varint(buf []byte) (int64, int)](#Varint) * [func ReadUvarint(r io.ByteReader) (uint64, error)](#ReadUvarint) * [func ReadVarint(r io.ByteReader) (int64, error)](#ReadVarint) * [func PutUvarint(buf []byte, x uint64) int](#PutUvarint) * [func PutVarint(buf []byte, x int64) int](#PutVarint) * [func Read(r io.Reader, order ByteOrder, data interface{}) error](#Read) * [func Write(w io.Writer, order ByteOrder, data interface{}) error](#Write) ### Examples * [Read](#example-Read) * [Write](#example-Write) * [Write (Multi)](#example-Write--Multi) ## Constants ``` const ( MaxVarintLen16 = 3 MaxVarintLen32 = 5 MaxVarintLen64 = 10 ) ``` 变长编码N位整数的最大字节数。 ## Variables ``` var BigEndian bigEndian ``` 大端字节序的实现。 ``` var LittleEndian littleEndian ``` 小端字节序的实现。 ## type [ByteOrder](https://github.com/golang/go/blob/master/src/encoding/binary/binary.go#L32 "View Source") ``` 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比特的无符号整数互相转化。 ## func [Size](https://github.com/golang/go/blob/master/src/encoding/binary/binary.go#L339 "View Source") ``` func Size(v interface{}) int ``` 返回v编码后会占用多少字节，注意v必须是定长值、定长值的切片、定长值的指针。 ## func [Uvarint](https://github.com/golang/go/blob/master/src/encoding/binary/varint.go#L60 "View Source") ``` func Uvarint(buf []byte) (uint64, int) ``` 从buf解码一个uint64，返回该数字和读取的字节长度，如果发生了错误，该数字为0而读取长度n返回值的意思是： ``` n == 0: buf不完整，太短了 n < 0: 值太大了，64比特装不下（溢出），-n为读取的字节数 ``` ## func [Varint](https://github.com/golang/go/blob/master/src/encoding/binary/varint.go#L94 "View Source") ``` func Varint(buf []byte) (int64, int) ``` 从buf解码一个int64，返回该数字和读取的字节长度，如果发生了错误，该数字为0而读取长度n返回值的意思是： ``` n == 0: buf不完整，太短了 n < 0: 值太大了，64比特装不下（溢出），-n为读取的字节数 ``` ## func [ReadUvarint](https://github.com/golang/go/blob/master/src/encoding/binary/varint.go#L106 "View Source") ``` func ReadUvarint(r io.ByteReader) (uint64, error) ``` 从r读取一个编码后的无符号整数，并返回该整数。 ## func [ReadVarint](https://github.com/golang/go/blob/master/src/encoding/binary/varint.go#L126 "View Source") ``` func ReadVarint(r io.ByteReader) (int64, error) ``` 从r读取一个编码后的有符号整数，并返回该整数。 ## func [PutUvarint](https://github.com/golang/go/blob/master/src/encoding/binary/varint.go#L41 "View Source") ``` func PutUvarint(buf []byte, x uint64) int ``` 将一个uint64数字编码写入buf并返回写入的长度，如果buf太小，则会panic。 ## func [PutVarint](https://github.com/golang/go/blob/master/src/encoding/binary/varint.go#L78 "View Source") ``` func PutVarint(buf []byte, x int64) int ``` 将一个int64数字编码写入buf并返回写入的长度，如果buf太小，则会panic。 ## func [Read](https://github.com/golang/go/blob/master/src/encoding/binary/binary.go#L137 "View Source") ``` func Read(r io.Reader, order ByteOrder, data interface{}) error ``` 从r中读取binary编码的数据并赋给data，data必须是一个指向定长值的指针或者定长值的切片。从r读取的字节使用order指定的字节序解码并写入data的字段里当写入结构体是，名字中有'_'的字段会被跳过，这些字段可用于填充（内存空间）。 Example ``` 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 ``` ## func [Write](https://github.com/golang/go/blob/master/src/encoding/binary/binary.go#L230 "View Source") ``` func Write(w io.Writer, order ByteOrder, data interface{}) error ``` 将data的binary编码格式写入w，data必须是定长值、定长值的切片、定长值的指针。order指定写入数据的字节序，写入结构体时，名字中有'_'的字段会置为0。 Example ``` 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) ``` 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 ```