# 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 ```