io: documentation for ByteScanner and RuneScanner does not match common implementations

[bcmills]

What version of Go are you using (go version)?

go1.17.1

Does this issue reproduce with the latest release?

Yes.

What did you do?

Compare the documentation for io.ByteScanner and io.RuneScanner to the behavior of common standard-library implementations (strings.Reader, bytes.Reader, bytes.Buffer, bufio.Reader).

What did you expect to see?

Behavior consistent with the io interface documentation (https://pkg.go.dev/io@go1.17.1#ByteScanner):

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.

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.

What did you see instead?

A mix of reasonable and less-reasonable behaviors, none of which match the io interface documentation.

• strings.Reader and bytes.Reader.
  • UnreadByte functions like Seek(-1, io.SeekCurrent). It returns nil as long as the current offset is ≥ 1, even if no read at all has occurred (such as if the offset has only been moved by Seek).
    • (https://play.golang.org/p/GpYEciJG0so)
  • UnreadRune returns nil only if the last method call that adjusted the offset was UnreadRune, even if the portion of the buffer immediately ahead of the current offset contains a complete, valid rune.
• bytes.Buffer:
  • UnreadByte returns nil as long as the last operation was any kind of Read, or Next (but not WriteTo, which is similarly Read-like).
  • UnreadRune returns nil only if the last operation was ReadRune.
• bufio.Reader:
  • UnreadByte returns nil as long as the last operation was any kind of Read, modulo buggy tracking for a few methods (bufio: Reader.UnreadByte after Discard silently corrupts input #48446).
  • UnreadRune returns nil only if the last operation was ReadRune (modulo the aforementioned bug).

As in #48316, I think that given the long-established behaviors of these implementations we must fix the io interface documentation instead of the de-facto behavior. I suggest that we change the documentation to read:

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.

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.

CC @robpike @griesemer @bradfitz @ianlancetaylor

[robpike]

SGTM

[gopherbot]

Change https://golang.org/cl/351809 mentions this issue: io: update ByteScanner and RuneScanner docs to match long-standing implementations