binary

package
v1.25.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 5, 2025 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

binaryパッケージは、数値とバイトシーケンスの間の単純な変換、 およびvarintのエンコードとデコードを実装します。

数値は、固定サイズの値を読み書きすることによって変換されます。 固定サイズの値は、固定サイズの算術型（bool、int8、uint8、int16、float32、complex64など） または固定サイズの値のみを含む配列または構造体です。

varint関数は、可変長エンコーディングを使用して単一の整数値をエンコードおよびデコードします。 より小さい値は、より少ないバイトを必要とします。 仕様については、以下を参照してください。 https://developers.google.com/protocol-buffers/docs/encoding。

このパッケージは、効率よりもシンプルさを重視しています。 特に大規模なデータ構造に対して高性能なシリアル化が必要なクライアントは、 encoding/gob パッケージやプロトコルバッファ google.golang.org/protobuf などのより高度なソリューションを検討する必要があります。

Index

Examples

Constants

View Source 
const (
	MaxVarintLen16 = 3
	MaxVarintLen32 = 5
	MaxVarintLen64 = 10
)

MaxVarintLenNは、Nビット整数の可変長エンコードの最大長です。

Variables

View Source 
var BigEndian bigEndian

BigEndianは、ByteOrder および AppendByteOrder のビッグエンディアン実装です。

View Source 
var LittleEndian littleEndian

LittleEndianは、ByteOrder および AppendByteOrder のリトルエンディアン実装です。

View Source 
var NativeEndian nativeEndian

NativeEndian is the native-endian implementation of ByteOrder and AppendByteOrder.

Functions

func Append added in v1.23.0 

func Append(buf []byte, order ByteOrder, data any) ([]byte, error)

Appendは、dataのバイナリ表現をbufに追加します。 bufはnilでも構いません。その場合、新しいバッファが割り当てられます。 どのようなdataが受け入れられるかについては、Write を参照してください。 dataを含む（場合によっては拡張された）バッファまたはエラーを返します。

func AppendUvarint added in v1.19.0 

func AppendUvarint(buf []byte, x uint64) []byte

AppendUvarintは、PutUvarint によって生成されたxのvarintエンコード形式をbufに追加し、拡張されたバッファを返します。

func AppendVarint added in v1.19.0 

func AppendVarint(buf []byte, x int64) []byte

AppendVarintは、PutVarint によって生成されたxのvarintエンコード形式をbufに追加し、拡張されたバッファを返します。

func Decode added in v1.23.0 

func Decode(buf []byte, order ByteOrder, data any) (int, error)

Decodeは、指定されたバイトオーダーに従って、bufからデータにバイナリデータをデコードします。 bufが小さすぎる場合はエラーを返し、それ以外の場合はbufから消費されたバイト数を返します。

func Encode added in v1.23.0 

func Encode(buf []byte, order ByteOrder, data any) (int, error)

Encodeは、指定されたバイトオーダーに従って、データのバイナリ表現をbufにエンコードします。 bufが小さすぎる場合はエラーを返し、それ以外の場合はbufに書き込まれたバイト数を返します。

func PutUvarint 

func PutUvarint(buf []byte, x uint64) int

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 

func PutVarint(buf []byte, x int64) int

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 

func Read(r io.Reader, order ByteOrder, data any) error

Readは、rからdataに対して構造化されたバイナリデータを読み取ります。 dataは、固定サイズの値または固定サイズの値のスライスへのポインタである必要があります。 rから読み取られたバイトは、指定されたバイトオーダーを使用してデコードされ、 dataの連続するフィールドに書き込まれます。 ブール値をデコードする場合、ゼロバイトはfalseとしてデコードされ、 それ以外の非ゼロバイトはtrueとしてデコードされます。 構造体に読み込む場合、ブランク（_）フィールド名を持つフィールドのデータはスキップされます。 つまり、パディングにブランクフィールド名を使用できます。 構造体に読み込む場合、すべての非ブランクフィールドはエクスポートされている必要があります。 そうでない場合、Readはパニックを引き起こす可能性があります。

エラーが io.EOF であるのは、バイトが読み込まれなかった場合のみです。 一部のバイトが読み込まれた後に io.EOF が発生した場合、 Readは io.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として返します。 エラーが 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は、値vをエンコードするために Write が生成するバイト数を返します。 vは、固定サイズの値または固定サイズの値のスライス、またはそのようなデータへのポインタである必要があります。 vがこれらのいずれでもない場合、Sizeは-1を返します。

func Uvarint 

func Uvarint(buf []byte) (uint64, int)

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 

func Varint(buf []byte) (int64, int)

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 

func Write(w io.Writer, order ByteOrder, data any) error

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ビットの符号なし整数をバイトスライスに追加する方法を指定します。

これは 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 によって実装されています。

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.