[インデックス 10585] ファイルの概要

このコミットは、Go言語の公式ドキュメント doc/devel/weekly.html における記述の修正です。具体的には、hash.Hash インターフェースの Sum メソッドの変更に関する説明が訂正されています。

コミット

commit 517503dab8cab086b431c9cb1a9292ce9831a629
Author: Andrew Gerrand <adg@golang.org>
Date:   Fri Dec 2 13:36:21 2011 +1100

    doc: correct weekly snapshot notes on hash.Hash change
    
    I had the wrong idea when I wrote this.
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5437111

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/517503dab8cab086b431c9cb1a9292ce9831a629

元コミット内容

doc/devel/weekly.html の以下の記述が修正されました。

--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -20,8 +20,8 @@ hg update weekly.<i>YYYY-MM-DD</i>
 This weekly snapshot includes changes to the hash package and a gofix for the
 time and os.FileInfo changes in the last snapshot.
 
-The hash.Hasher's Sum method has been given a []byte argument, permitting
-the user to hash an arbitrary byte slice without Writing to the Hasher.
+The hash.Hash's Sum method has been given a []byte argument,
+permitting the user to append the hash to an existing byte slice.
 Existing code that uses Sum can pass nil as the argument.
 Gofix will make this change automatically.

変更の背景

このコミットの背景には、Go言語の標準ライブラリである hash パッケージ内の hash.Hash インターフェースの Sum メソッドのシグネチャ変更があります。元のドキュメントの記述が、この変更の意図を誤って伝えていたため、その誤りを訂正するためにこのコミットが作成されました。

Andrew Gerrand氏が「I had the wrong idea when I wrote this.（これを書いた時、私は間違った考えを持っていた）」と述べていることから、ドキュメントの執筆者が Sum メソッドの新しい引数の目的を当初誤解していたことが伺えます。

前提知識の解説

Go言語の hash パッケージと hash.Hash インターフェース

Go言語の crypto パッケージ群は、様々な暗号学的ハッシュ関数（MD5, SHA-1, SHA-256など）を提供しています。これらのハッシュ関数は、hash.Hash インターフェースを実装しています。

hash.Hash インターフェースは、以下の主要なメソッドを定義しています（当時のバージョンに基づく）：

• Write(p []byte) (n int, err error): ハッシュ計算の対象となるデータを追加します。ストリーム処理のようにデータを少しずつ渡すことができます。
• Sum(b []byte) []byte: 現在までに Write されたデータからハッシュ値を計算し、その結果を b の末尾に追加して返します。この b 引数が今回の変更の焦点です。
• Reset(): ハッシュの状態を初期化します。
• Size() int: ハッシュ値のバイト長を返します。
• BlockSize() int: ハッシュ関数のブロックサイズを返します。

Sum メソッドの役割と変更点

Sum メソッドは、ハッシュ計算の最終段階で呼び出され、計算されたハッシュ値をバイトスライスとして返します。

変更前の Sum メソッドのシグネチャは Sum() []byte であったと考えられます。この場合、ハッシュ値は常に新しいバイトスライスとして返されます。

変更後の Sum メソッドのシグネチャは Sum(b []byte) []byte となりました。この変更の意図は、呼び出し元が既存のバイトスライス b を提供し、ハッシュ値がそのスライスの末尾に追加されるようにすることです。これにより、特にハッシュ値を他のデータと連結する場合に、余分なメモリ割り当てを避けることができます。

gofix ツール

gofix は、Go言語のツールチェーンの一部であり、GoのAPIが変更された際に、古いAPIを使用しているコードを新しいAPIに自動的に書き換えるためのツールです。Go言語は後方互換性を非常に重視していますが、言語や標準ライブラリの進化に伴い、APIの変更が必要になる場合があります。gofix は、このような変更による開発者の負担を軽減するために提供されています。

このコミットメッセージにある「Gofix will make this change automatically.」という記述は、hash.Hash の Sum メソッドのシグネチャ変更が gofix によって自動的に修正されることを意味しています。これにより、既存のコードベースが新しいAPIに対応するために手動で修正する必要がなくなります。

技術的詳細

このコミットは、Go言語のドキュメント doc/devel/weekly.html の内容を修正することで、hash.Hash インターフェースの Sum メソッドの変更に関する正確な情報を提供することを目的としています。

元の記述： The hash.Hasher's Sum method has been given a []byte argument, permitting the user to hash an arbitrary byte slice without Writing to the Hasher. （hash.Hasher の Sum メソッドに []byte 引数が与えられ、ユーザーが Hasher に Write せずに任意のバイトスライスをハッシュ化できるようになりました。）

修正後の記述： The hash.Hash's Sum method has been given a []byte argument, permitting the user to append the hash to an existing byte slice. （hash.Hash の Sum メソッドに []byte 引数が与えられ、ユーザーが既存のバイトスライスにハッシュを追加できるようになりました。）

この修正のポイントは以下の通りです。

1. hash.Hasher から hash.Hash への訂正: Go言語の hash パッケージには Hasher という型は存在せず、正しくは Hash インターフェースです。これは単純な誤字または誤認の修正です。
2. Sum メソッドの引数の目的の訂正:
   • 元の誤解: Sum メソッドの []byte 引数が、Write メソッドを使わずに直接バイトスライスをハッシュ化するためのものだと誤解されていました。これは、Sum メソッドがハッシュ計算の「最終結果」を生成する役割を持つという理解と矛盾します。ハッシュ計算の対象となるデータは通常 Write メソッドを通じて提供されます。
   • 正しい理解: Sum メソッドの []byte 引数 b は、計算されたハッシュ値を b の末尾に追加するためのものです。これにより、呼び出し元は既存のバッファを再利用したり、複数のハッシュ値を連結したりする際に、余分なメモリ割り当てを避けることができます。例えば、Sum(nil) と呼び出すことで、新しいバイトスライスとしてハッシュ値を取得することも可能です。

この変更は、Go言語のAPI設計における効率性と柔軟性を追求する姿勢を示しています。特に、メモリ割り当てを最小限に抑えることは、パフォーマンスが重要なGoアプリケーションにおいて重要な考慮事項です。

コアとなるコードの変更箇所

変更は doc/devel/weekly.html ファイルの以下の部分です。

--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -20,8 +20,8 @@ hg update weekly.<i>YYYY-MM-DD</i>
 This weekly snapshot includes changes to the hash package and a gofix for the
 time and os.FileInfo changes in the last snapshot.
 
-The hash.Hasher's Sum method has been given a []byte argument, permitting
-the user to hash an arbitrary byte slice without Writing to the Hasher.
+The hash.Hash's Sum method has been given a []byte argument,
+permitting the user to append the hash to an existing byte slice.
 Existing code that uses Sum can pass nil as the argument.
 Gofix will make this change automatically.

コアとなるコードの解説

この変更は、HTMLドキュメント内のテキストコンテンツの修正であり、Go言語のソースコードそのものの変更ではありません。しかし、このドキュメントの修正は、Go言語のAPIの正確な理解を促進するために非常に重要です。

具体的には、以下の2行が変更されています。

1. -The hash.Hasher's Sum method has been given a []byte argument, permitting +The hash.Hash's Sum method has been given a []byte argument, この行では、hash.Hasher という誤った型名が hash.Hash という正しいインターフェース名に修正されています。また、行の途中で改行されていた部分が削除され、次の行と結合されています。

2. -the user to hash an arbitrary byte slice without Writing to the Hasher. +permitting the user to append the hash to an existing byte slice. この行では、Sum メソッドの []byte 引数の目的に関する説明が完全に書き換えられています。

   • 元の「Write せずに任意のバイトスライスをハッシュ化できる」という誤った説明が削除されました。
   • 新しい「既存のバイトスライスにハッシュを追加できる」という正確な説明が追加されました。

この修正により、Go言語のユーザーは hash.Hash インターフェースの Sum メソッドの正しい使い方と意図を理解できるようになります。特に、Sum(nil) を渡すことで新しいスライスとしてハッシュ値を取得できること、そして既存のスライスにハッシュ値を追加できるという柔軟性が強調されています。

関連リンク

• Go言語の hash パッケージのドキュメント (現在のバージョン): https://pkg.go.dev/hash
• Go言語の gofix ツールに関する情報: gofix はGoのリリースノートやブログ記事で言及されることが多いですが、専用の公式ドキュメントページは少ないです。Goのバージョンアップに伴う変更点の自動修正ツールとして理解されています。

参考にした情報源リンク

• Go言語の公式ドキュメント (特に hash パッケージのAPIリファレンス)
• Go言語のコミット履歴と関連するコードレビュー (Gerrit CL: https://golang.org/cl/5437111)
• Go言語のブログやリリースノート (過去のAPI変更に関する情報)
• Go言語の gofix ツールに関する一般的な知識

[インデックス 10585] ファイルの概要

このコミットは、Go言語の公式ドキュメント doc/devel/weekly.html における記述の修正です。具体的には、hash.Hash インターフェースの Sum メソッドの変更に関する説明が訂正されています。

コミット

commit 517503dab8cab086b431c9cb1a9292ce9831a629
Author: Andrew Gerrand <adg@golang.org>
Date:   Fri Dec 2 13:36:21 2011 +1100

    doc: correct weekly snapshot notes on hash.Hash change
    
    I had the wrong idea when I wrote this.
    
    R=golang-dev, rsc
    CC=golang-dev
    https://golang.org/cl/5437111

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/517503dab8cab086b431c9cb1a9292ce9831a629

元コミット内容

doc/devel/weekly.html の以下の記述が修正されました。

--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -20,8 +20,8 @@ hg update weekly.<i>YYYY-MM-DD</i>
 This weekly snapshot includes changes to the hash package and a gofix for the
 time and os.FileInfo changes in the last snapshot.
 
-The hash.Hasher's Sum method has been given a []byte argument, permitting
-the user to hash an arbitrary byte slice without Writing to the Hasher.
+The hash.Hash's Sum method has been given a []byte argument,
+permitting the user to append the hash to an existing byte slice.
 Existing code that uses Sum can pass nil as the argument.
 Gofix will make this change automatically.

変更の背景

このコミットの背景には、Go言語の標準ライブラリである hash パッケージ内の hash.Hash インターフェースの Sum メソッドのシグネチャ変更に関する、ドキュメントの記述の誤りがありました。元のドキュメントの記述が、この変更の意図を誤って伝えていたため、その誤りを訂正するためにこのコミットが作成されました。

Andrew Gerrand氏がコミットメッセージで「I had the wrong idea when I wrote this.（これを書いた時、私は間違った考えを持っていた）」と述べていることから、ドキュメントの執筆者が Sum メソッドの新しい引数の目的を当初誤解していたことが伺えます。これは、APIの変更が導入された際に、その意図が正確に伝わらないことがあり得るという良い例です。

前提知識の解説

Go言語の hash パッケージと hash.Hash インターフェース

Go言語の crypto パッケージ群は、様々な暗号学的ハッシュ関数（MD5, SHA-1, SHA-256など）を提供しています。これらのハッシュ関数は、hash.Hash インターフェースを実装しています。

hash.Hash インターフェースは、ハッシュ計算を行うための共通のインターフェースを定義しており、主なメソッドは以下の通りです。

• Write(p []byte) (n int, err error): ハッシュ計算の対象となるデータを追加します。このメソッドは、ストリーム処理のようにデータを少しずつ渡すことを可能にします。
• Sum(b []byte) []byte: 現在までに Write されたデータからハッシュ値を計算し、その結果を b の末尾に追加して返します。この b 引数が今回のドキュメント修正の焦点です。
• Reset(): ハッシュの状態を初期化し、再利用できるようにします。
• Size() int: ハッシュ値のバイト長を返します。
• BlockSize() int: ハッシュ関数のブロックサイズを返します。

Sum メソッドの役割と変更点

Sum メソッドは、ハッシュ計算の最終段階で呼び出され、計算されたハッシュ値をバイトスライスとして返します。

Go 1以降、Sum メソッドのシグネチャは一貫して Sum(b []byte) []byte です。この設計は、効率性を考慮したものであり、ユーザーが既存のバイトスライスを再利用し、メモリ割り当てを最小限に抑えることを可能にします。

• Sum(b []byte) []byte の意図: このメソッドは、計算されたハッシュ値を引数 b で渡されたバイトスライスの末尾に追加し、その結果のスライスを返します。これにより、呼び出し元は、ハッシュ値を格納するための新しいスライスを毎回割り当てる必要がなくなります。例えば、複数のハッシュ値を連結するようなシナリオで特に有用です。
• Sum(nil) の使用: もしハッシュ値を新しいバイトスライスとして取得したい場合は、Sum(nil) と呼び出すことができます。この場合、Sum メソッドは内部で新しいスライスを割り当ててハッシュ値を格納し、それを返します。

元のドキュメントの記述は、この b []byte 引数の目的を「Write せずに任意のバイトスライスをハッシュ化する」と誤解していました。しかし、Sum メソッドはあくまで「これまでに Write されたデータのハッシュ値を計算する」ものであり、引数 b はその結果をどこに格納するか、という目的で使われます。ハッシュ計算の対象となるデータ自体は、通常 Write メソッドを通じて提供されます。

gofix ツール

gofix は、Go言語のツールチェーンの一部であり、GoのAPIが変更された際に、古いAPIを使用しているコードを新しいAPIに自動的に書き換えるためのツールです。Go言語は後方互換性を非常に重視していますが、言語や標準ライブラリの進化に伴い、APIの変更が必要になる場合があります。gofix は、このような変更による開発者の負担を軽減するために提供されています。

このコミットメッセージにある「Gofix will make this change automatically.」という記述は、hash.Hash の Sum メソッドのシグネチャ変更が gofix によって自動的に修正されることを意味しています。これにより、既存のコードベースが新しいAPIに対応するために手動で修正する必要がなくなります。これは、Go言語が大規模なコードベースのメンテナンスを容易にするために提供する強力な機能の一つです。

技術的詳細

このコミットは、Go言語のドキュメント doc/devel/weekly.html の内容を修正することで、hash.Hash インターフェースの Sum メソッドの変更に関する正確な情報を提供することを目的としています。

元の記述： The hash.Hasher's Sum method has been given a []byte argument, permitting the user to hash an arbitrary byte slice without Writing to the Hasher. （hash.Hasher の Sum メソッドに []byte 引数が与えられ、ユーザーが Hasher に Write せずに任意のバイトスライスをハッシュ化できるようになりました。）

修正後の記述： The hash.Hash's Sum method has been given a []byte argument, permitting the user to append the hash to an existing byte slice. （hash.Hash の Sum メソッドに []byte 引数が与えられ、ユーザーが既存のバイトスライスにハッシュを追加できるようになりました。）

この修正のポイントは以下の通りです。

1. hash.Hasher から hash.Hash への訂正: Go言語の hash パッケージには Hasher という具体的な型は存在せず、正しくは Hash インターフェースです。これは単純な誤字または誤認の修正であり、正確なAPI名を反映しています。
2. Sum メソッドの引数の目的の訂正:
   • 元の誤解: Sum メソッドの []byte 引数が、Write メソッドを使わずに直接バイトスライスをハッシュ化するためのものだと誤解されていました。これは、Sum メソッドがハッシュ計算の「最終結果」を生成する役割を持つという理解と矛盾します。ハッシュ計算の対象となるデータは通常 Write メソッドを通じてハッシュオブジェクトに供給されます。
   • 正しい理解: Sum メソッドの []byte 引数 b は、計算されたハッシュ値を b の末尾に追加するためのものです。これにより、呼び出し元は既存のバッファを再利用したり、複数のハッシュ値を連結したりする際に、余分なメモリ割り当てを避けることができます。この設計は、Go言語がパフォーマンスと効率性を重視する哲学を反映しています。例えば、Sum(nil) と呼び出すことで、新しいバイトスライスとしてハッシュ値を取得することも可能です。

この変更は、Go言語のAPI設計における効率性と柔軟性を追求する姿勢を示しています。特に、メモリ割り当てを最小限に抑えることは、パフォーマンスが重要なGoアプリケーションにおいて重要な考慮事項です。ドキュメントの正確性は、開発者がAPIを正しく理解し、効果的に利用するために不可欠です。

コアとなるコードの変更箇所

変更は doc/devel/weekly.html ファイルの以下の部分です。

--- a/doc/devel/weekly.html
+++ b/doc/devel/weekly.html
@@ -20,8 +20,8 @@ hg update weekly.<i>YYYY-MM-DD</i>
 This weekly snapshot includes changes to the hash package and a gofix for the
 time and os.FileInfo changes in the last snapshot.
 
-The hash.Hasher's Sum method has been given a []byte argument, permitting
-the user to hash an arbitrary byte slice without Writing to the Hasher.
+The hash.Hash's Sum method has been given a []byte argument,
+permitting the user to append the hash to an existing byte slice.
 Existing code that uses Sum can pass nil as the argument.
 Gofix will make this change automatically.

コアとなるコードの解説

この変更は、HTMLドキュメント内のテキストコンテンツの修正であり、Go言語のソースコードそのものの変更ではありません。しかし、このドキュメントの修正は、Go言語のAPIの正確な理解を促進するために非常に重要です。

具体的には、以下の2行が変更されています。

1. -The hash.Hasher's Sum method has been given a []byte argument, permitting +The hash.Hash's Sum method has been given a []byte argument, この行では、hash.Hasher という誤った型名が hash.Hash という正しいインターフェース名に修正されています。また、元の行の途中で改行されていた部分が削除され、次の行と結合されることで、より自然な文章の流れになっています。

2. -the user to hash an arbitrary byte slice without Writing to the Hasher. +permitting the user to append the hash to an existing byte slice. この行では、Sum メソッドの []byte 引数の目的に関する説明が完全に書き換えられています。

   • 元の「Write せずに任意のバイトスライスをハッシュ化できる」という誤った説明が削除されました。これは、Sum メソッドの本来の役割（これまでに Write されたデータのハッシュ値を返す）と矛盾するため、非常に重要な修正です。
   • 新しい「既存のバイトスライスにハッシュを追加できる」という正確な説明が追加されました。これにより、Sum メソッドの b []byte 引数が、メモリ効率の良い方法でハッシュ結果を既存のバッファに格納するためのものであることが明確に示されています。

この修正により、Go言語のユーザーは hash.Hash インターフェースの Sum メソッドの正しい使い方と意図を理解できるようになります。特に、Sum(nil) を渡すことで新しいスライスとしてハッシュ値を取得できること、そして既存のスライスにハッシュ値を追加できるという柔軟性が強調されています。これは、Go言語のAPI設計における実用性とパフォーマンスへの配慮を示すものです。

関連リンク

• Go言語の hash パッケージのドキュメント (現在のバージョン): https://pkg.go.dev/hash
• Go言語の gofix ツールに関する情報: gofix はGoのリリースノートやブログ記事で言及されることが多いですが、専用の公式ドキュメントページは少ないです。Goのバージョンアップに伴う変更点の自動修正ツールとして理解されています。

参考にした情報源リンク

• Go言語の公式ドキュメント (特に hash パッケージのAPIリファレンス)
• Go言語のコミット履歴と関連するコードレビュー (Gerrit CL: https://golang.org/cl/5437111)
• Go言語のブログやリリースノート (過去のAPI変更に関する情報)
• Go言語の gofix ツールに関する一般的な知識
• Web検索結果: "Go hash.Hash Sum method change 2011" (Go 1以降、Sum メソッドのシグネチャは Sum(b []byte) []byte で一貫しているという情報)