package binary
import "encoding/binary"
binary包实现了简单的数字与字节序列的转换以及变长值的编解码。
数字翻译为定长值来读写,一个定长值,要么是固定长度的数字类型(int8, uint8, int16, float32, complex64, ...)或者只包含定长值的结构体或者数组。
变长值是使用一到多个字节编码整数的方法,绝对值较小的数字会占用较少的字节数。详情请参见:http://code.google.com/apis/protocolbuffers/docs/encoding.html。
本包相对于效率更注重简单。如果需要高效的序列化,特别是数据结构较复杂的,请参见更高级的解决方法,例如encoding/gob包,或者采用协议缓存。
Index
- Constants
- Variables
- type ByteOrder
- func Size(v interface{}) int
- func Uvarint(buf []byte) (uint64, int)
- func Varint(buf []byte) (int64, int)
- func ReadUvarint(r io.ByteReader) (uint64, error)
- func ReadVarint(r io.ByteReader) (int64, error)
- func PutUvarint(buf []byte, x uint64) int
- func PutVarint(buf []byte, x int64) int
- func Read(r io.Reader, order ByteOrder, data interface{}) error
- func Write(w io.Writer, order ByteOrder, data interface{}) error
Examples
Constants
const (
MaxVarintLen16 = 3
MaxVarintLen32 = 5
MaxVarintLen64 = 10
)
变长编码N位整数的最大字节数。
Variables
var BigEndian bigEndian
大端字节序的实现。
var LittleEndian littleEndian
小端字节序的实现。
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比特的无符号整数互相转化。
func Size
func Size(v interface{}) int
返回v编码后会占用多少字节,注意v必须是定长值、定长值的切片、定长值的指针。
func Uvarint
func Uvarint(buf []byte) (uint64, int)
从buf解码一个uint64,返回该数字和读取的字节长度,如果发生了错误,该数字为0而读取长度n返回值的意思是:
n == 0: buf不完整,太短了
n < 0: 值太大了,64比特装不下(溢出),-n为读取的字节数
func Varint
func Varint(buf []byte) (int64, int)
从buf解码一个int64,返回该数字和读取的字节长度,如果发生了错误,该数字为0而读取长度n返回值的意思是:
n == 0: buf不完整,太短了
n < 0: 值太大了,64比特装不下(溢出),-n为读取的字节数
func ReadUvarint
func ReadUvarint(r io.ByteReader) (uint64, error)
从r读取一个编码后的无符号整数,并返回该整数。
func ReadVarint
func ReadVarint(r io.ByteReader) (int64, error)
从r读取一个编码后的有符号整数,并返回该整数。
func PutUvarint
func PutUvarint(buf []byte, x uint64) int
将一个uint64数字编码写入buf并返回写入的长度,如果buf太小,则会panic。
func PutVarint
func PutVarint(buf []byte, x int64) int
将一个int64数字编码写入buf并返回写入的长度,如果buf太小,则会panic。
func Read
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
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