Documentation
¶
Overview ¶
binaryパッケージは、数値とバイトシーケンスの間の単純な変換、 およびvarintのエンコードとデコードを実装します。
数値は、固定サイズの値を読み書きすることによって変換されます。 固定サイズの値は、固定サイズの算術型（bool、int8、uint8、int16、float32、complex64など） または固定サイズの値のみを含む配列または構造体です。
varint関数は、可変長エンコーディングを使用して単一の整数値をエンコードおよびデコードします。 より小さい値は、より少ないバイトを必要とします。 仕様については、以下を参照してください。 https://developers.google.com/protocol-buffers/docs/encoding。
このパッケージは、効率よりもシンプルさを重視しています。 特に大規模なデータ構造に対して高性能なシリアル化が必要なクライアントは、 encoding/gobパッケージやプロトコルバッファなどのより高度なソリューションを検討する必要があります。
Index ¶
- Constants
- Variables
- func AppendUvarint(buf []byte, x uint64) []byte
- func AppendVarint(buf []byte, x int64) []byte
- 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 ¶
Constants ¶
const ( MaxVarintLen16 = 3 MaxVarintLen32 = 5 MaxVarintLen64 = 10 )
MaxVarintLenNは、Nビット整数の可変長エンコードの最大長です。
Variables ¶
var BigEndian bigEndian
BigEndianは、ByteOrderおよびAppendByteOrderのビッグエンディアン実装です。
var LittleEndian littleEndian
LittleEndianは、ByteOrderおよびAppendByteOrderのリトルエンディアン実装です。
var NativeEndian nativeEndian
NativeEndian is the native-endian implementation of ByteOrder and AppendByteOrder.
Functions ¶
func AppendUvarint ¶ added in v1.19.0
AppendUvarintは、PutUvarintによって生成されたxのvarintエンコード形式をbufに追加し、拡張されたバッファを返します。
func AppendVarint ¶ added in v1.19.0
AppendVarintは、PutVarintによって生成されたxのvarintエンコード形式をbufに追加し、拡張されたバッファを返します。
func PutUvarint ¶
PutUvarintは、uint64をbufにエンコードし、書き込まれたバイト数を返します。 バッファが小さすぎる場合、PutUvarintはパニックを引き起こします。
Example ¶
package main
import (
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 ¶
PutVarintは、int64をbufにエンコードし、書き込まれたバイト数を返します。 バッファが小さすぎる場合、PutVarintはパニックを引き起こします。
Example ¶
package main
import (
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 ¶
Readは、rからdataに対して構造化されたバイナリデータを読み取ります。 dataは、固定サイズの値または固定サイズの値のスライスへのポインタである必要があります。 rから読み取られたバイトは、指定されたバイトオーダーを使用してデコードされ、 dataの連続するフィールドに書き込まれます。 ブール値をデコードする場合、ゼロバイトはfalseとしてデコードされ、 それ以外の非ゼロバイトはtrueとしてデコードされます。 構造体に読み込む場合、ブランク（_）フィールド名を持つフィールドのデータはスキップされます。 つまり、パディングにブランクフィールド名を使用できます。 構造体に読み込む場合、すべての非ブランクフィールドはエクスポートされている必要があります。 そうでない場合、Readはパニックを引き起こす可能性があります。
エラーがEOFであるのは、バイトが読み込まれなかった場合のみです。 一部のバイトが読み込まれた後にEOFが発生した場合、 ReadはErrUnexpectedEOFを返します。
Example ¶
package main
import (
"github.com/shogo82148/std/bytes"
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 (
"github.com/shogo82148/std/bytes"
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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として返します。 エラーがEOFであるのは、バイトが読み込まれなかった場合のみです。 一部のバイトが読み込まれた後にEOFが発生した場合、 ReadUvarintはio.ErrUnexpectedEOFを返します。
func ReadVarint ¶
func ReadVarint(r io.ByteReader) (int64, error)
ReadVarintは、rから符号付き整数を読み取り、int64として返します。 エラーがEOFであるのは、バイトが読み込まれなかった場合のみです。 一部のバイトが読み込まれた後にEOFが発生した場合、 ReadVarintはio.ErrUnexpectedEOFを返します。
func Size ¶
Sizeは、値vをエンコードするためにWriteが生成するバイト数を返します。 vは、固定サイズの値または固定サイズの値のスライス、またはそのようなデータへのポインタである必要があります。 vがこれらのいずれでもない場合、Sizeは-1を返します。
func Uvarint ¶
Uvarintは、bufからuint64をデコードし、その値と読み取られたバイト数（> 0）を返します。 エラーが発生した場合、値は0で、バイト数nは<= 0です。
n == 0: バッファが小さすぎます n < 0: 64ビットより大きい値（オーバーフロー）で、-nは読み取られたバイト数です
Example ¶
package main
import (
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 ¶
Varintは、bufからint64をデコードし、その値と読み取られたバイト数（> 0）を返します。 エラーが発生した場合、値は0で、バイト数nは<= 0です。
n == 0: バッファが小さすぎます n < 0: 64ビットより大きい値（オーバーフロー）で、-nは読み取られたバイト数です
Example ¶
package main
import (
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 ¶
Writeは、データのバイナリ表現をwに書き込みます。 データは、固定サイズの値または固定サイズの値のスライス、またはそのようなデータへのポインタである必要があります。 ブール値は1がtrue、0がfalseとして1バイトでエンコードされます。 wに書き込まれたバイトは、指定されたバイトオーダーを使用してエンコードされ、 データの連続するフィールドから読み取られます。 構造体を書き込む場合、ブランク（_）フィールド名を持つフィールドのデータはゼロ値で書き込まれます。
Example ¶
package main
import (
"github.com/shogo82148/std/bytes"
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/fmt"
"github.com/shogo82148/std/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 (
"github.com/shogo82148/std/bytes"
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 ¶ added in v1.19.0
type AppendByteOrder interface {
AppendUint16([]byte, uint16) []byte
AppendUint32([]byte, uint32) []byte
AppendUint64([]byte, uint64) []byte
String() string
}
AppendByteOrderは、16、32、または64ビットの符号なし整数をバイトスライスに追加する方法を指定します。
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ビットの符号なし整数に変換する方法を指定します。
Example (Get) ¶
package main
import (
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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 (
"github.com/shogo82148/std/encoding/binary"
"github.com/shogo82148/std/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
Source Files