github.com/shogo82148/std@v1.22.1-0.20240327122250-4e474527810c/encoding/binary/binary.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // binaryパッケージは、数値とバイトシーケンスの間の単純な変換、
     6  // およびvarintのエンコードとデコードを実装します。
     7  //
     8  // 数値は、固定サイズの値を読み書きすることによって変換されます。
     9  // 固定サイズの値は、固定サイズの算術型（bool、int8、uint8、int16、float32、complex64など）
    10  // または固定サイズの値のみを含む配列または構造体です。
    11  //
    12  // varint関数は、可変長エンコーディングを使用して単一の整数値をエンコードおよびデコードします。
    13  // より小さい値は、より少ないバイトを必要とします。
    14  // 仕様については、以下を参照してください。
    15  // https://developers.google.com/protocol-buffers/docs/encoding。
    16  //
    17  // このパッケージは、効率よりもシンプルさを重視しています。
    18  // 特に大規模なデータ構造に対して高性能なシリアル化が必要なクライアントは、
    19  // [encoding/gob] パッケージやプロトコルバッファ [google.golang.org/protobuf] などのより高度なソリューションを検討する必要があります。
    20  package binary
    21  
    22  import (
    23  	"github.com/shogo82148/std/io"
    24  )
    25  
    26  // ByteOrderは、バイトスライスを16、32、または64ビットの符号なし整数に変換する方法を指定します。
    27  //
    28  // これは [LittleEndian]、[BigEndian]、および [NativeEndian] によって実装されています。
    29  type ByteOrder interface {
    30  	Uint16([]byte) uint16
    31  	Uint32([]byte) uint32
    32  	Uint64([]byte) uint64
    33  	PutUint16([]byte, uint16)
    34  	PutUint32([]byte, uint32)
    35  	PutUint64([]byte, uint64)
    36  	String() string
    37  }
    38  
    39  // AppendByteOrderは、16、32、または64ビットの符号なし整数をバイトスライスに追加する方法を指定します。
    40  //
    41  // これは [LittleEndian]、[BigEndian]、および [NativeEndian] によって実装されています。
    42  type AppendByteOrder interface {
    43  	AppendUint16([]byte, uint16) []byte
    44  	AppendUint32([]byte, uint32) []byte
    45  	AppendUint64([]byte, uint64) []byte
    46  	String() string
    47  }
    48  
    49  // LittleEndianは、[ByteOrder] および [AppendByteOrder] のリトルエンディアン実装です。
    50  var LittleEndian littleEndian
    51  
    52  // BigEndianは、[ByteOrder] および [AppendByteOrder] のビッグエンディアン実装です。
    53  var BigEndian bigEndian
    54  
    55  // Readは、rからdataに対して構造化されたバイナリデータを読み取ります。
    56  // dataは、固定サイズの値または固定サイズの値のスライスへのポインタである必要があります。
    57  // rから読み取られたバイトは、指定されたバイトオーダーを使用してデコードされ、
    58  // dataの連続するフィールドに書き込まれます。
    59  // ブール値をデコードする場合、ゼロバイトはfalseとしてデコードされ、
    60  // それ以外の非ゼロバイトはtrueとしてデコードされます。
    61  // 構造体に読み込む場合、ブランク（_）フィールド名を持つフィールドのデータはスキップされます。
    62  // つまり、パディングにブランクフィールド名を使用できます。
    63  // 構造体に読み込む場合、すべての非ブランクフィールドはエクスポートされている必要があります。
    64  // そうでない場合、Readはパニックを引き起こす可能性があります。
    65  //
    66  // エラーが [io.EOF] であるのは、バイトが読み込まれなかった場合のみです。
    67  // 一部のバイトが読み込まれた後に [io.EOF] が発生した場合、
    68  // Readは [io.ErrUnexpectedEOF] を返します。
    69  func Read(r io.Reader, order ByteOrder, data any) error
    70  
    71  // Writeは、データのバイナリ表現をwに書き込みます。
    72  // データは、固定サイズの値または固定サイズの値のスライス、またはそのようなデータへのポインタである必要があります。
    73  // ブール値は1がtrue、0がfalseとして1バイトでエンコードされます。
    74  // wに書き込まれたバイトは、指定されたバイトオーダーを使用してエンコードされ、
    75  // データの連続するフィールドから読み取られます。
    76  // 構造体を書き込む場合、ブランク（_）フィールド名を持つフィールドのデータはゼロ値で書き込まれます。
    77  func Write(w io.Writer, order ByteOrder, data any) error
    78  
    79  // Sizeは、値vをエンコードするために [Write] が生成するバイト数を返します。
    80  // vは、固定サイズの値または固定サイズの値のスライス、またはそのようなデータへのポインタである必要があります。
    81  // vがこれらのいずれでもない場合、Sizeは-1を返します。
    82  func Size(v any) int