Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

このコミットは、Go言語の標準ライブラリbytesパッケージ内のBuffer型のAPIに関する修正とドキュメントの改善を目的としています。具体的には、NewBufferおよびNewBufferString関数のドキュメントの明確化と、Buffer.Truncateメソッドが不正な引数を受け取った際の挙動の修正（パニックの導入）が含まれています。

コミット

commit 0a75a79cc063d0149921c2248c6ef0fa9583174d
Author: Rob Pike <r@golang.org>
Date:   Mon Feb 6 15:29:21 2012 +1100

    bytes: API tweaks
    - fix documentation for NewBuffer and NewBufferString
    - document and implement behavior of Truncate on invalid lengths
    
    Fixes #2837.
    
    R=rsc, adg
    CC=golang-dev
    https://golang.org/cl/5637044

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

https://github.com/golang/go/commit/0a75a79cc063d0149921c2248c6ef0fa9583174d

元コミット内容

bytes: API tweaks
- fix documentation for NewBuffer and NewBufferString
- document and implement behavior of Truncate on invalid lengths

Fixes #2837.

変更の背景

このコミットは、Go言語のbytesパッケージにおけるBuffer型のAPIの使いやすさと堅牢性を向上させるために行われました。特に、GitHub Issue #2837で議論された問題に対処しています。

主な背景は以下の2点です。

  1. NewBufferとNewBufferStringの誤解を招くドキュメント: 既存のドキュメントでは、これらの関数がBufferを初期化する際に、渡されたバイトスライスや文字列がどのように扱われるかについて、誤解を招く可能性がありました。特に、NewBufferに非空の[]byteを渡した後にBufferに書き込むと、元の[]byteが上書きされる可能性があるという重要な注意点が不明瞭でした。多くのユーザーは、渡されたデータがバッファの初期内容として「追加」されると誤解する可能性がありました。
  2. Truncateメソッドの不正な引数処理: Buffer.Truncate(n)メソッドは、バッファの長さをnバイトに切り詰めるためのものです。しかし、nが負の値であったり、現在のバッファの長さよりも大きい値であったりした場合の挙動が明確に定義されておらず、予期せぬ動作やクラッシュを引き起こす可能性がありました。堅牢なAPI設計では、このような不正な入力に対して明確で予測可能な挙動を提供する必要があります。

これらの問題に対処することで、bytes.BufferのAPIがより直感的で安全に使用できるようになり、開発者が予期せぬバグに遭遇するリスクを低減することが目的でした。

前提知識の解説

bytes.Bufferとは

bytes.Bufferは、Go言語の標準ライブラリbytesパッケージで提供される、可変長のバイトバッファを実装した型です。これは、バイトスライス（[]byte）を効率的に操作するための便利な機能を提供します。主な用途としては、文字列の構築、I/O操作（io.Readerやio.Writerインターフェースの実装）、データの蓄積などが挙げられます。内部的にはバイトスライスを保持し、必要に応じてその容量を自動的に拡張します。

NewBuffer関数

func NewBuffer(buf []byte) *Buffer この関数は、指定されたバイトスライスbufを初期内容として持つ新しいBufferを生成し、そのポインタを返します。重要なのは、bufがバッファの初期内容として「コピーされる」のではなく、「内部のバイトスライスとして直接使用される」という点です。そのため、NewBufferに渡したbufを後で変更すると、Bufferの内容も変更される可能性があります。また、Bufferに書き込み操作を行うと、元のbufの内容が上書きされることがあります。

NewBufferString関数

func NewBufferString(s string) *Buffer この関数は、指定された文字列sを初期内容として持つ新しいBufferを生成し、そのポインタを返します。内部的には、文字列sをバイトスライスに変換してBufferの初期内容とします。NewBufferと同様に、初期化後のバッファへの書き込みが元の文字列とは独立して行われる点に注意が必要です。

Buffer.Truncateメソッド

func (b *Buffer) Truncate(n int) このメソッドは、Bufferの読み込まれていないバイトのうち、最初のnバイトだけを残し、残りを破棄します。つまり、バッファの長さをnに切り詰めます。nが0の場合、バッファは空になります。

panicとは

Go言語におけるpanicは、プログラムの実行を中断させるためのメカニズムです。これは、通常、回復不可能なエラーやプログラマの論理的な誤りを示すために使用されます。panicが発生すると、現在の関数の実行が直ちに停止し、遅延関数（defer）が実行され、呼び出しスタックを遡ってpanicが伝播します。もし途中でrecoverによって捕捉されなければ、プログラムはクラッシュします。API設計において、不正な引数など、プログラムが続行できないような状態になった場合にpanicを使用することは、そのAPIの契約違反を明確に通知する手段として有効です。

技術的詳細

このコミットでは、主に以下の2つの技術的な変更が行われました。

  1. Buffer.Truncateメソッドの挙動変更:

    • 変更前は、n > b.Len()の場合にエラーとなるというドキュメントがありましたが、実際の挙動は未定義でした。
    • 変更後は、nが負の値（n < 0）であるか、またはバッファの現在の長さよりも大きい値（n > b.Len()）である場合に、panicを発生させるように修正されました。具体的には、panic("bytes.Buffer: truncation out of range")というメッセージでパニックします。
    • これにより、Truncateメソッドの契約が明確になり、不正な引数に対する挙動が予測可能かつ堅牢になりました。

  2. NewBufferおよびNewBufferString関数のドキュメント修正:

    • 変更前は、これらの関数がBufferを初期化する際の挙動、特に渡された[]byteやstringがどのように扱われるかについて、誤解を招く可能性のある記述がありました。
    • 変更後は、new(Buffer)（または単にBuffer変数を宣言すること）がほとんどの場合でBufferの初期化に十分であるという点が強調されました。
    • 特にNewBufferについては、「非空のbufをNewBufferに渡し、その後Bufferに書き込むと、bufが上書きされ、追加されない」という重要な注意点が削除され、代わりに「ほとんどの場合、new(Buffer)（または単にBuffer変数を宣言すること）がBufferの初期化に十分である」という、より一般的な推奨事項が記載されました。これは、NewBufferの特定のユースケース（既存のバイトスライスを直接ラップしたい場合）を考慮しつつ、一般的な誤用を防ぐための変更です。
    • NewBufferStringについても同様に、「NewBufferに関する警告を参照してください。同様の問題がここに適用されます」という記述が削除され、new(Buffer)による初期化が推奨されるという記述が追加されました。

これらの変更は、APIの堅牢性を高め、開発者がbytes.Bufferをより安全かつ意図通りに使用できるようにすることを目的としています。特にTruncateにおけるpanicの導入は、契約違反を早期に検出し、プログラムの不正な状態での続行を防ぐためのGoらしいアプローチです。

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

--- a/src/pkg/bytes/buffer.go
+++ b/src/pkg/bytes/buffer.go
@@ -57,10 +57,13 @@ func (b *Buffer) String() string {
 func (b *Buffer) Len() int { return len(b.buf) - b.off }
 
 // Truncate discards all but the first n unread bytes from the buffer.
-// It is an error to call b.Truncate(n) with n > b.Len().
+// It panics if n is negative or greater than the length of the buffer.
 func (b *Buffer) Truncate(n int) {
  b.lastRead = opInvalid
-\tif n == 0 {\n+\tswitch {\n+\tcase n < 0 || n > b.Len():\n+\t\tpanic(\"bytes.Buffer: truncation out of range\")\n+\tcase n == 0:\
  // Reuse buffer space.
  b.off = 0
  }
@@ -366,14 +369,15 @@ func (b *Buffer) ReadString(delim byte) (line string, err error) {
 // buf should have the desired capacity but a length of zero.
 //
 // In most cases, new(Buffer) (or just declaring a Buffer variable) is
-// preferable to NewBuffer.  In particular, passing a non-empty buf to
-// NewBuffer and then writing to the Buffer will overwrite buf, not append to
-// it.\n+// sufficient to initialize a Buffer.\
 func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} }\
 
 // NewBufferString creates and initializes a new Buffer using string s as its
-// initial contents.  It is intended to prepare a buffer to read an existing
-// string.  See the warnings about NewBuffer; similar issues apply here.\n+// initial contents. It is intended to prepare a buffer to read an existing
+// string.\n+//\n+// In most cases, new(Buffer) (or just declaring a Buffer variable) is\n+// sufficient to initialize a Buffer.\
 func NewBufferString(s string) *Buffer {
  return &Buffer{buf: []byte(s)}\
 }\

コアとなるコードの解説

Buffer.Truncateメソッドの変更

変更の核心は、Truncateメソッドの冒頭にswitch文が導入された点です。

 func (b *Buffer) Truncate(n int) {
 	b.lastRead = opInvalid
-	if n == 0 {
+	switch {
+	case n < 0 || n > b.Len():
+		panic("bytes.Buffer: truncation out of range")
+	case n == 0:
 		// Reuse buffer space.
 		b.off = 0
 	}
  • switch文の導入: 以前はif n == 0という単純な条件分岐でしたが、より複雑な条件を扱うためにswitch文が使用されました。Goのswitch文は、式を伴わない場合、最初のcaseがtrueになったブロックが実行されます。
  • 不正なnのチェック:
    • case n < 0 || n > b.Len(): この行が追加されました。nが負の値であるか、または現在のバッファの長さ（b.Len()）よりも大きい場合にこのcaseがマッチします。
    • panic("bytes.Buffer: truncation out of range"): 上記の条件が満たされた場合、指定されたエラーメッセージと共にpanicが発生します。これにより、Truncateメソッドが不正な引数で呼び出された際に、プログラムが即座に異常終了し、問題が早期に検出されるようになります。これは、APIの契約違反に対する明確なシグナルです。
  • n == 0の処理: 以前のif n == 0のロジックは、case n == 0:としてswitch文内に移動されました。この部分は、バッファを空にする（b.off = 0）という既存の挙動を維持しています。

NewBufferおよびNewBufferString関数のドキュメント変更

これらの関数のコメントが大幅に修正され、より明確で誤解の少ない記述になりました。

NewBufferのドキュメント変更

 // In most cases, new(Buffer) (or just declaring a Buffer variable) is
-// preferable to NewBuffer.  In particular, passing a non-empty buf to
-// NewBuffer and then writing to the Buffer will overwrite buf, not append to
-// it.\n+// sufficient to initialize a Buffer.\
 func NewBuffer(buf []byte) *Buffer { return &Buffer{buf: buf} }\
  • 以前のドキュメントは、「NewBufferよりもnew(Buffer)が好ましい」と述べ、さらに「非空のbufをNewBufferに渡し、その後Bufferに書き込むと、bufが上書きされ、追加されない」という具体的な警告を含んでいました。
  • 新しいドキュメントは、より簡潔に「ほとんどの場合、new(Buffer)（または単にBuffer変数を宣言すること）がBufferの初期化に十分である」と述べています。これにより、NewBufferの特定の挙動に関する詳細な警告が削除され、一般的な初期化方法が推奨される形になりました。これは、NewBufferが特定の高度なユースケース（既存のバイトスライスを直接ラップして効率を最大化したい場合など）のために存在し、一般的な用途ではnew(Buffer)で十分であることを示唆しています。

NewBufferStringのドキュメント変更

 // NewBufferString creates and initializes a new Buffer using string s as its
-// initial contents.  It is intended to prepare a buffer to read an existing
-// string.  See the warnings about NewBuffer; similar issues apply here.\n+// initial contents. It is intended to prepare a buffer to read an existing
+// string.\n+//\n+// In most cases, new(Buffer) (or just declaring a Buffer variable) is\n+// sufficient to initialize a Buffer.\
 func NewBufferString(s string) *Buffer {
  return &Buffer{buf: []byte(s)}\
 }\
  • 以前のドキュメントは、「NewBufferに関する警告を参照してください。同様の問題がここに適用されます」と述べていました。
  • 新しいドキュメントは、NewBufferと同様に、「ほとんどの場合、new(Buffer)（または単にBuffer変数を宣言すること）がBufferの初期化に十分である」という推奨事項を追加しました。これにより、NewBufferStringの初期化に関する誤解も解消され、より一般的な初期化方法が推奨されるようになりました。

これらの変更は、GoのAPIドキュメントの品質向上と、開発者がより安全かつ効率的にbytes.Bufferを使用できるようにするためのものです。

関連リンク

参考にした情報源リンク