bufio: document that Scanner.Buffer is to avoid buffer allocation, not specify scanner input.

[SineSwiper]

Go version

go version go1.24.3 linux/amd64

Output of go env in your module/workspace:

AR='ar'
CC='gcc'
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_ENABLED='1'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
CXX='g++'
GCCGO='gccgo'
GO111MODULE=''
GOAMD64='v1'
GOARCH='amd64'
GOAUTH='netrc'
GOBIN=''
GOCACHEPROG=''
GODEBUG=''
GOEXE=''
GOEXPERIMENT=''
GOFIPS140='off'
GOFLAGS=''
GOGCCFLAGS='-fPIC -m64 -pthread -Wl,--no-gc-sections -fmessage-length=0 -ffile-prefix-map=/var/tmp/go-build2282435825=/tmp/go-build -gno-record-gcc-switches'
GOHOSTARCH='amd64'
GOHOSTOS='linux'
GOINSECURE=''
GOMOD='/dev/null'
GOOS='linux'
GOPROXY='https://proxy.golang.org,direct'
GOSUMDB='sum.golang.org'
GOTELEMETRY='local'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOVCS=''
GOVERSION='go1.24.3'
GOWORK=''
PKG_CONFIG='pkg-config'

What did you do?

Ran scanner.Buffer(leftoverBuffer, bufio.MaxScanTokenSize), which runs the code here.

What did you see happen?

A scanner.Scan() call clobbers the buffer data that was provided, based on this line here.

What did you expect to see?

The Scanner.Buffer function actually using the data provided by the first argument. Because s.end is not set, the data is lost, which makes the first argument completely useless.

[adonovan]

My read of the doc comment at Scanner.Buffer is that it exists to allow the caller to provide an array, to avoid a possibly expensive allocation, not that this array should contain the input to the scanner, which is always provided by the io.Reader passed to NewScanner. So this is working as intended, though perhaps the docs could be clarified.

[SineSwiper]

So, how should one provide an actual "initial buffer" (with contents) to the scanner?

Or does that need to be added into the split function? Right now, I'm doing that for both setting leftoverBuffer and prepending data with leftoverBuffer on the receiving side. (There's no way to read the buffer from the scanner, either.) Although, I was hoping there was a more elegant solution through Scanner functions.

[adonovan]

So, how should one provide an actual "initial buffer" (with contents) to the scanner?

Pass it to NewScanner. You can use io.MultiReader(bytes.NewReader(prefix), os.Stdin) to concatenate two readers relatively efficiently.

[gopherbot]

Change https://go.dev/cl/674695 mentions this issue: bufio: update buffer documentation