bufio: document relationship between UnreadByte/UnreadRune and Peek
Fixes #29387
Change-Id: I2d9981f63ac16630ed39d6da6692c81396f4e9ea
Reviewed-on: https://go-review.googlesource.com/c/155930
Reviewed-by: Ian Lance Taylor <iant@golang.org>
diff --git a/src/bufio/bufio.go b/src/bufio/bufio.go
index ffb278a..0125d72 100644
--- a/src/bufio/bufio.go
+++ b/src/bufio/bufio.go
@@ -33,8 +33,8 @@
rd io.Reader // reader provided by the client
r, w int // buf read and write positions
err error
- lastByte int
- lastRuneSize int
+ lastByte int // last byte read for UnreadByte; -1 means invalid
+ lastRuneSize int // size of last rune read for UnreadRune; -1 means invalid
}
const minReadBufferSize = 16
@@ -123,6 +123,9 @@
// being valid at the next read call. If Peek returns fewer than n bytes, it
// also returns an error explaining why the read is short. The error is
// ErrBufferFull if n is larger than b's buffer size.
+//
+// Calling Peek prevents a UnreadByte or UnreadRune call from succeeding
+// until the next read operation.
func (b *Reader) Peek(n int) ([]byte, error) {
if n < 0 {
return nil, ErrNegativeCount
@@ -252,6 +255,10 @@
}
// UnreadByte unreads the last byte. Only the most recently read byte can be unread.
+//
+// UnreadByte returns an error if the most recent method called on the
+// Reader was not a read operation. Notably, Peek is not considered a
+// read operation.
func (b *Reader) UnreadByte() error {
if b.lastByte < 0 || b.r == 0 && b.w > 0 {
return ErrInvalidUnreadByte
@@ -290,8 +297,8 @@
return r, size, nil
}
-// UnreadRune unreads the last rune. If the most recent read operation on
-// the buffer was not a ReadRune, UnreadRune returns an error. (In this
+// UnreadRune unreads the last rune. If the most recent method called on
+// the Reader was not a ReadRune, UnreadRune returns an error. (In this
// regard it is stricter than UnreadByte, which will unread the last byte
// from any read operation.)
func (b *Reader) UnreadRune() error {
