# Packages
ascii85パッケージはbtoaツールやAdobeのPostScriptおよびPDFドキュメント形式で使用されているascii85データエンコーディングを実装しています。.
パッケージasn1は、ITU-T Rec X.690で定義されたDERエンコードされたASN.1データ構造の解析を実装します。 また、「ASN.1、BER、およびDERのサブセットの素人向けガイド」も参照してください。 http://luca.ntop.org/Teaching/Appunti/asn1.html。.
base32パッケージは、RFC 4648で指定されているように、base32エンコーディングを実装します。.
base64パッケージは、RFC 4648で指定されているように、base64エンコーディングを実装します。.
binaryパッケージは、数値とバイトシーケンスの間の単純な変換、 およびvarintのエンコードとデコードを実装します。
数値は、固定サイズの値を読み書きすることによって変換されます。 固定サイズの値は、固定サイズの算術型(bool、int8、uint8、int16、float32、complex64など) または固定サイズの値のみを含む配列または構造体です。
varint関数は、可変長エンコーディングを使用して単一の整数値をエンコードおよびデコードします。 より小さい値は、より少ないバイトを必要とします。 仕様については、以下を参照してください。 https://developers.google.com/protocol-buffers/docs/encoding。
このパッケージは、効率よりもシンプルさを重視しています。 特に大規模なデータ構造に対して高性能なシリアル化が必要なクライアントは、 [encoding/gob] パッケージやプロトコルバッファ [google.golang.org/protobuf] などのより高度なソリューションを検討する必要があります。.
csvパッケージは、カンマ区切り値(CSV)ファイルの読み書きを行います。 多くの種類のCSVファイルがありますが、このパッケージはRFC 4180で説明されている形式をサポートしています。 ただし、[Writer] はデフォルトで改行文字としてCRLFではなくLFを使用します。
CSVファイルには、レコードごとに1つ以上のフィールドを含むゼロ以上のレコードが含まれています。 各レコードは改行文字で区切られます。最後のレコードはオプションで改行文字に続くことができます。
field1,field2,field3
空白はフィールドの一部と見なされます。
改行文字の前のキャリッジリターンは、静かに削除されます。
空行は無視されます。空白文字のみで構成される行(末尾の改行文字を除く)は、空行と見なされません。
クォート文字 "で始まり、終わるフィールドは、クォートフィールドと呼ばれます。 開始と終了の引用符はフィールドの一部ではありません。
ソース:
normal string,"quoted-field"
は、次のフィールドを生成します。
{`normal string`, `quoted-field`}
クォートフィールド内の引用符の後に2番目の引用符が続く場合、 1つの引用符として扱われます。
"the ""word"" is true","a ""quoted-field"""
の結果は次のとおりです。
{`the "word" is true`, `a "quoted-field"`}
改行とカンマは、クォートフィールド内に含めることができます。
"Multi-line field","comma is ,"
の結果は次のとおりです。
{`Multi-line field`, `comma is ,`}.
gobパッケージは、gobのストリームを管理します - これは、
[Encoder](送信者)と [Decoder](受信者)間で交換されるバイナリ値です。
典型的な使用例は、リモートプロシージャコール(RPC)の引数と結果を転送することです。
これは [net/rpc] によって提供されます。
実装は、ストリーム内の各データ型に対してカスタムコーデックをコンパイルし、
コンパイルのコストを分散させるために、単一の [Encoder] が値のストリームを送信するときに最も効率的です。
# 基本
gobのストリームは自己記述的です。ストリーム内の各データ項目は、
その型の仕様によって先行します。これは、事前に定義された小さな型セットの観点から表現されます。
ポインタは伝送されませんが、それらが指すものは伝送されます。つまり、値はフラット化されます。
nilポインタは許可されていません、なぜならそれらには値がないからです。
再帰的な型はうまく動作しますが、再帰的な値(サイクルを持つデータ)は問題となります。これは変わるかもしれません。
gobを使用するには、[Encoder] を作成し、それに一連のデータ項目を
値または値に逆参照できるアドレスとして提示します。[Encoder] は
すべての型情報が必要になる前に送信されることを確認します。受信側では、
[Decoder] がエンコードされたストリームから値を取得し、それらをローカル
変数に展開します。
# 型と値
ソースと宛先の値/型は、正確に一致する必要はありません。構造体の場合、
ソースに存在するが受信変数から欠落しているフィールド(名前で識別)は無視されます。
受信変数に存在するが、送信された型または値から欠落しているフィールドは、
宛先では無視されます。同じ名前のフィールドが両方に存在する場合、
その型は互換性がなければなりません。受信者と送信者の両方が、
gobと実際のGoの値との間で必要なすべての間接参照と逆参照を行います。
例えば、スキーマ的には、gobの型は以下のようになります。
struct { A, B int }
以下のGoの型から送信されるか、または受信することができます:
struct { A, B int } // 同じ
*struct { A, B int } // 構造体の追加の間接参照
struct { *A, **B int } // フィールドの追加の間接参照
struct { A, B int64 } // 異なる具体的な値の型; 下記参照
以下のいずれかにも受信することができます:
struct { A, B int } // 同じ
struct { B, A int } // 順序は関係ありません; 名前でマッチングします
struct { A, B, C int } // 追加のフィールド(C)は無視されます
struct { B int } // 欠落しているフィールド(A)は無視されます; データは破棄されます
struct { B, C int } // 欠落しているフィールド(A)は無視されます; 追加のフィールド(C)も無視されます。
これらの型に受信しようとすると、デコードエラーが発生します:
struct { A int; B uint } // Bの符号が変わります
struct { A int; B float } // Bの型が変わります
struct { } // 共通のフィールド名がありません
struct { C, D int } // 共通のフィールド名がありません
整数は2つの方法で伝送されます: 任意の精度を持つ符号付き整数または
任意の精度を持つ符号なし整数。gob形式ではint8、int16などの
区別はありません。符号付きと符号なしの整数のみが存在します。以下で
説明するように、送信者は可変長エンコーディングで値を送信します。
受信者は値を受け入れ、それを宛先変数に格納します。
浮動小数点数は常にIEEE 754 64ビット精度を使用して送信されます(以下参照)。
符号付き整数は任意の符号付き整数変数(int、int16など)に受け取ることができます。
符号なし整数は任意の符号なし整数変数に受け取ることができます。
浮動小数点数は任意の浮動小数点数変数に受け取ることができます。
ただし、宛先の変数は値を表現できる必要があります。そうでない場合、デコード操作は失敗します。
構造体、配列、スライスもサポートされています。構造体はエクスポートされた
フィールドのみをエンコードおよびデコードします。文字列とバイトの配列は、
特別で効率的な表現でサポートされています(下記参照)。スライスがデコードされるとき、
既存のスライスに容量がある場合、スライスはその場で拡張されます。そうでない場合、
新しい配列が割り当てられます。いずれにせよ、結果として得られるスライスの長さは、
デコードされた要素の数を報告します。
一般的に、割り当てが必要な場合、デコーダはメモリを割り当てます。そうでない場合、
ストリームから読み取った値で宛先の変数を更新します。最初にそれらを初期化することはありません。
したがって、宛先がマップ、構造体、またはスライスなどの複合値である場合、
デコードされた値は要素ごとに既存の変数にマージされます。
関数とチャネルはgobで送信されません。そのような値をトップレベルでエンコードしようとすると失敗します。
chan型またはfunc型の構造体フィールドは、エクスポートされていないフィールドと全く同じように扱われ、無視されます。
Gobは、[GobEncoder] または [encoding.BinaryMarshaler] インターフェースを実装する任意の型の値をエンコードできます。
これは、その順序の優先度で対応するメソッドを呼び出すことによって行われます。
Gobは、[GobDecoder] または [encoding.BinaryUnmarshaler] インターフェースを実装する任意の型の値をデコードできます。
これは、その順序の優先度で対応するメソッドを呼び出すことによって行われます。
# エンコーディングの詳細
このセクションでは、ほとんどのユーザーにとって重要でないエンコーディングの詳細を文書化します。
詳細は下から上に提示されます。
符号なし整数は2つの方法のいずれかで送信されます。それが128未満の場合、その値を持つバイトとして送信されます。
それ以外の場合、それは最小長のビッグエンディアン(高バイト先)バイトストリームとして送信され、
その前にバイト数を保持する1バイトが先行します。このバイト数は否定されます。
したがって、0は(00)として送信され、7は(07)として送信され、256は(FE 01 00)として送信されます。
ブール値は符号なし整数内にエンコードされます: falseの場合は0、trueの場合は1。
符号付き整数iは、符号なし整数u内にエンコードされます。u内で、ビット1以上が値を含み、
ビット0は受信時にそれらを補完するかどうかを示します。エンコードアルゴリズムは次のようになります:
var u uint
if i < 0 {
u = (^uint(i) << 1) | 1 // iを補完し、ビット0を1にします
} else {
u = (uint(i) << 1) // iを補完しない、ビット0は0です
}
encodeUnsigned(u)
したがって、低ビットは符号ビットに類似していますが、それを補完ビットにすることで、
最大の負の整数が特別なケースにならないことを保証します。例えば、-129=^128=(^256>>1)は(FE 01 01)としてエンコードされます。
浮動小数点数は常にfloat64値の表現として送信されます。
その値は [math.Float64bits] を使用してuint64に変換されます。そのuint64は
バイト反転され、通常の符号なし整数として送信されます。バイト反転により、
指数とマンティッサの高精度部分が最初に来ます。低ビットはしばしばゼロなので、
これによりエンコーディングバイトを節約できます。例えば、17.0は
3バイト(FE 31 40)でエンコードされます。
文字列とバイトのスライスは、符号なしのカウントとその後に続くその値の
未解釈のバイトとして送信されます。
その他のすべてのスライスと配列は、符号なしのカウントに続いてその要素数だけが
その型の標準的なgobエンコーディングを使用して再帰的に送信されます。
マップは、符号なしのカウントに続いてその数だけのキー、要素のペアとして送信されます。
空だがnilでないマップは送信されるので、受信者がすでに割り当てていない場合、
送信されたマップがnilでなく、トップレベルでない限り、受信時に常に割り当てられます。
スライスや配列、マップでは、すべての要素、ゼロ値の要素であっても、
すべての要素がゼロであっても、送信されます。
構造体は、(フィールド番号、フィールド値)のペアのシーケンスとして送信されます。フィールド
値はその型の標準的なgobエンコーディングを使用して、再帰的に送信されます。フィールドが
その型のゼロ値を持つ場合(配列を除く; 上記参照)、それは伝送から省略されます。フィールド番号は
エンコードされた構造体の型によって定義されます: エンコードされた型の最初のフィールドはフィールド0、
次のフィールドはフィールド1、等です。値をエンコードするとき、フィールド番号は効率のために
デルタエンコードされ、フィールドは常にフィールド番号の増加順に送信されます; したがって、デルタは
符号なしです。デルタエンコーディングの初期化はフィールド番号を-1に設定するので、値が7の符号なし整数フィールド0は
符号なしデルタ=1、符号なし値=7または(01 07)として送信されます。最後に、すべてのフィールドが
送信された後、終端マークが構造体の終わりを示します。そのマークはデルタ=0の
値で、表現は(00)です。
インターフェース型は互換性がチェックされません。すべてのインターフェース型は、
伝送のために、単一の "interface" 型のメンバーとして扱われます。これはintや[]byteに類似しています。
効果的に、すべてが interface{} として扱われます。インターフェース値は、送信される具体的な型を
識別する文字列として送信されます(この名前は [Register] を呼び出すことで事前に定義する必要があります)。
次に、次のデータの長さのバイト数(値が格納できない場合に値をスキップできるように)、
次にインターフェース値に格納されている具体的(動的)値の通常のエンコーディングが続きます。
(nilのインターフェース値は空の文字列によって識別され、値は送信されません。)
受信時に、デコーダは展開された具体的なアイテムが受信変数のインターフェースを満たしていることを確認します。
値が [Encoder.Encode] に渡され、その型が構造体(または構造体へのポインタなど)でない場合、
処理の簡便性のために、それは1つのフィールドを持つ構造体として表現されます。
これによる唯一の可視的な効果は、エンコードされた構造体の最後のフィールドの後と同様に、
値の後にゼロバイトをエンコードすることで、デコードアルゴリズムがトップレベルの値が完了したことを知ることができます。
型の表現については以下に説明します。型が [Encoder] と [Decoder] の間の特定の
接続で定義されると、それには符号付き整数型の
idが割り当てられます。 [Encoder.Encode](v)が呼び出されると、vの型とそのすべての要素に
idが割り当てられていることを確認し、次にペア(typeid, encoded-v)を送信します。
ここで、typeidはvのエンコードされた型の型idであり、encoded-vは値vのgob
エンコーディングです。
型を定義するために、エンコーダは未使用の正の型idを選択し、
ペア(-type id, encoded-type)を送信します。ここで、encoded-typeはwireType
記述のgobエンコーディングで、これらの型から構築されます:
type wireType struct {
ArrayT *arrayType
SliceT *sliceType
StructT *structType
MapT *mapType
GobEncoderT *gobEncoderType
BinaryMarshalerT *gobEncoderType
TextMarshalerT *gobEncoderType
}
type arrayType struct {
CommonType
Elem typeId
Len int
}
type CommonType struct {
Name string // the name of the struct type
Id int // the id of the type, repeated so it's inside the type
}
type sliceType struct {
CommonType
Elem typeId
}
type structType struct {
CommonType
Field []fieldType // the fields of the struct.
hexパッケージは16進数のエンコードとデコードを実装します。.
jsonパッケージは、RFC 7159で定義されているJSONのエンコーディングとデコーディングを実装します。 JSONとGoの値の間のマッピングは、Marshal関数とUnmarshal関数のドキュメンテーションで説明されています。
このパッケージの紹介については、「JSONとGo」を参照してください: https://golang.org/doc/articles/json_and_go.html.
pemパッケージは、プライバシー拡張メールで起源を持つPEMデータのエンコーディングを実装しています。現在最も一般的なPEMエンコーディングの使用法は、TLSキーと証明書です。RFC 1421を参照してください。.
xmlパッケージは、XML名前空間を理解する シンプルなXML 1.0パーサーを実装します。.
# Interfaces
BinaryAppender is the interface implemented by an object that can append the binary representation of itself.
BinaryMarshalerは、自身をバイナリ形式に変換できるオブジェクトによって実装されるインターフェースです。
MarshalBinaryは、レシーバをバイナリ形式にエンコードし、その結果を返します。.
BinaryUnmarshalerは、自身のバイナリ表現をアンマーシャルできるオブジェクトによって実装されるインターフェースです。
UnmarshalBinaryは、MarshalBinaryによって生成された形式をデコードできる必要があります。 UnmarshalBinaryは、データを保持したい場合はデータをコピーする必要があります。 処理を終えた後のデータを残したい場合は、データをコピーする必要があります。.
TextAppender is the interface implemented by an object that can append the textual representation of itself.
TextMarshalerは、自身をテキスト形式にマーシャリングできるオブジェクトによって実装されるインターフェースです。
MarshalTextは、レシーバをUTF-8でエンコードされたテキストに変換し、結果を返します。.
TextUnmarshalerは、自身のテキスト表現をUnmarshalできるオブジェクトが実装するインターフェースです。
UnmarshalTextは、MarshalTextによって生成された形式をデコードできる必要があります。 UnmarshalTextは、戻り値の後にテキストを保持する場合は、テキストをコピーする必要があります。.