io: update ByteScanner and RuneScanner docs to match long-standing implementations

Do not require the byte or rune unread by the call to match the last
return from ReadByte or ReadRune, since in practice the
implementations of these methods (especially ReadByte) may also unread
bytes from other Read-style methods without reporting an error.

Explicitly allow the Seek-like behavior implemented by bytes.Reader
and bufio.Reader, which can “unread” bytes that were never actually
read.

Explicitly allow ReadByte or ReadRune to return an error after a call
to a non-ReadByte or non-ReadRune operation respectively.
(In practice, implementations today allow very liberal calls to
ReadByte and tend to be more strict about ReadRune, but it seems
simpler to keep the two definitions completely parallel.)

Like CL 349054, this is techincally a breaking change, but given the
long-standing behavior of the implementations in the Go standard
library (such as strings.Reader, bytes.Buffer, and bufio.Reader),
I believe it falls under the “specification errors” exception to the
Go 1 compatibility policy.

Fixes #48449

Change-Id: I61696a59770fe83c667377ba25a072762d3f6f19
Reviewed-on: https://go-review.googlesource.com/c/go/+/351809
Trust: Bryan C. Mills <bcmills@google.com>
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>

1 files changed, 10 insertions, 8 deletions

diff --git a/src/io/io.go b/src/io/io.go
index cb2a37e427..ceac7ba7f8 100644
--- a/src/io/io.go
+++ b/src/io/io.go
@@ -262,10 +262,11 @@ type ByteReader interface {
 // ByteScanner is the interface that adds the UnreadByte method to the
 // basic ReadByte method.
 //
-// UnreadByte causes the next call to ReadByte to return the same byte
-// as the previous call to ReadByte.
-// It may be an error to call UnreadByte twice without an intervening
-// call to ReadByte.
+// UnreadByte causes the next call to ReadByte to return the last byte read.
+// If the last operation was not a successful call to ReadByte, UnreadByte may
+// return an error, unread the last byte read (or the byte prior to the
+// last-unread byte), or (in implementations that support the Seeker interface)
+// seek to one byte before the current offset.
 type ByteScanner interface {
 	ByteReader
 	UnreadByte() error
@@ -288,10 +289,11 @@ type RuneReader interface {
 // RuneScanner is the interface that adds the UnreadRune method to the
 // basic ReadRune method.
 //
-// UnreadRune causes the next call to ReadRune to return the same rune
-// as the previous call to ReadRune.
-// It may be an error to call UnreadRune twice without an intervening
-// call to ReadRune.
+// UnreadRune causes the next call to ReadRune to return the last rune read.
+// If the last operation was not a successful call to ReadRune, UnreadRune may
+// return an error, unread the last rune read (or the rune prior to the
+// last-unread rune), or (in implementations that support the Seeker interface)
+// seek to the start of the rune before the current offset.
 type RuneScanner interface {
 	RuneReader
 	UnreadRune() error