bufio
packagestandard library
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Report a Vulnerability
Documentation¶
Overview¶
Package bufio implements buffered I/O. It wraps an io.Reader or io.Writerobject, creating another object (Reader or Writer) that also implementsthe interface but provides buffering and some help for textual I/O.
Index¶
- Constants
- Variables
- func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error)
- func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error)
- func ScanRunes(data []byte, atEOF bool) (advance int, token []byte, err error)
- func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error)
- type ReadWriter
- type Reader
- func (b *Reader) Buffered() int
- func (b *Reader) Discard(n int) (discarded int, err error)
- func (b *Reader) Peek(n int) ([]byte, error)
- func (b *Reader) Read(p []byte) (n int, err error)
- func (b *Reader) ReadByte() (byte, error)
- func (b *Reader) ReadBytes(delim byte) ([]byte, error)
- func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error)
- func (b *Reader) ReadRune() (r rune, size int, err error)
- func (b *Reader) ReadSlice(delim byte) (line []byte, err error)
- func (b *Reader) ReadString(delim byte) (string, error)
- func (b *Reader) Reset(r io.Reader)
- func (b *Reader) Size() int
- func (b *Reader) UnreadByte() error
- func (b *Reader) UnreadRune() error
- func (b *Reader) WriteTo(w io.Writer) (n int64, err error)
- type Scanner
- type SplitFunc
- type Writer
- func (b *Writer) Available() int
- func (b *Writer) AvailableBuffer() []byte
- func (b *Writer) Buffered() int
- func (b *Writer) Flush() error
- func (b *Writer) ReadFrom(r io.Reader) (n int64, err error)
- func (b *Writer) Reset(w io.Writer)
- func (b *Writer) Size() int
- func (b *Writer) Write(p []byte) (nn int, err error)
- func (b *Writer) WriteByte(c byte) error
- func (b *Writer) WriteRune(r rune) (size int, err error)
- func (b *Writer) WriteString(s string) (int, error)
Examples¶
Constants¶
const (// MaxScanTokenSize is the maximum size used to buffer a token// unless the user provides an explicit buffer with [Scanner.Buffer].// The actual maximum token size may be smaller as the buffer// may need to include, for instance, a newline.MaxScanTokenSize = 64 * 1024)
Variables¶
var (ErrInvalidUnreadByte =errors.New("bufio: invalid use of UnreadByte")ErrInvalidUnreadRune =errors.New("bufio: invalid use of UnreadRune")ErrBufferFull =errors.New("bufio: buffer full")ErrNegativeCount =errors.New("bufio: negative count"))
var (ErrTooLong =errors.New("bufio.Scanner: token too long")ErrNegativeAdvance =errors.New("bufio.Scanner: SplitFunc returns negative advance count")ErrAdvanceTooFar =errors.New("bufio.Scanner: SplitFunc returns advance count beyond input")ErrBadReadCount =errors.New("bufio.Scanner: Read returned impossible count"))
Errors returned by Scanner.
var ErrFinalToken =errors.New("final token")ErrFinalToken is a special sentinel error value. It is intended to bereturned by a Split function to indicate that the scanning should stopwith no error. If the token being delivered with this error is not nil,the token is the last token.
The value is useful to stop processing early or when it is necessary todeliver a final empty token (which is different from a nil token).One could achieve the same behavior with a custom error value butproviding one here is tidier.See the emptyFinalToken example for a use of this value.
Functions¶
funcScanBytes¶added ingo1.1
ScanBytes is a split function for aScanner that returns each byte as a token.
funcScanLines¶added ingo1.1
ScanLines is a split function for aScanner that returns each line oftext, stripped of any trailing end-of-line marker. The returned line maybe empty. The end-of-line marker is one optional carriage return followedby one mandatory newline. In regular expression notation, it is `\r?\n`.The last non-empty line of input will be returned even if it has nonewline.
funcScanRunes¶added ingo1.1
ScanRunes is a split function for aScanner that returns eachUTF-8-encoded rune as a token. The sequence of runes returned isequivalent to that from a range loop over the input as a string, whichmeans that erroneous UTF-8 encodings translate to U+FFFD = "\xef\xbf\xbd".Because of the Scan interface, this makes it impossible for the client todistinguish correctly encoded replacement runes from encoding errors.
Types¶
typeReadWriter¶
ReadWriter stores pointers to aReader and aWriter.It implementsio.ReadWriter.
funcNewReadWriter¶
func NewReadWriter(r *Reader, w *Writer) *ReadWriter
NewReadWriter allocates a newReadWriter that dispatches to r and w.
typeReader¶
type Reader struct {// contains filtered or unexported fields}Reader implements buffering for an io.Reader object.A new Reader is created by callingNewReader orNewReaderSize;alternatively the zero value of a Reader may be used after calling [Reset]on it.
funcNewReaderSize¶
NewReaderSize returns a newReader whose buffer has at least the specifiedsize. If the argument io.Reader is already aReader with large enoughsize, it returns the underlyingReader.
func (*Reader)Buffered¶
Buffered returns the number of bytes that can be read from the current buffer.
func (*Reader)Discard¶added ingo1.5
Discard skips the next n bytes, returning the number of bytes discarded.
If Discard skips fewer than n bytes, it also returns an error.If 0 <= n <= b.Buffered(), Discard is guaranteed to succeed withoutreading from the underlying io.Reader.
func (*Reader)Peek¶
Peek returns the next n bytes without advancing the reader. The bytes stopbeing valid at the next read call. If necessary, Peek will read more bytesinto the buffer in order to make n bytes available. If Peek returns fewerthan n bytes, it also returns an error explaining why the read is short.The error isErrBufferFull if n is larger than b's buffer size.
Calling Peek prevents aReader.UnreadByte orReader.UnreadRune call from succeedinguntil the next read operation.
func (*Reader)Read¶
Read reads data into p.It returns the number of bytes read into p.The bytes are taken from at most one Read on the underlyingReader,hence n may be less than len(p).To read exactly len(p) bytes, use io.ReadFull(b, p).If the underlyingReader can return a non-zero count with io.EOF,then this Read method can do so as well; see theio.Reader docs.
func (*Reader)ReadByte¶
ReadByte reads and returns a single byte.If no byte is available, returns an error.
func (*Reader)ReadBytes¶
ReadBytes reads until the first occurrence of delim in the input,returning a slice containing the data up to and including the delimiter.If ReadBytes encounters an error before finding a delimiter,it returns the data read before the error and the error itself (often io.EOF).ReadBytes returns err != nil if and only if the returned data does not end indelim.For simple uses, a Scanner may be more convenient.
func (*Reader)ReadLine¶
ReadLine is a low-level line-reading primitive. Most callers should useReader.ReadBytes('\n') orReader.ReadString('\n') instead or use aScanner.
ReadLine tries to return a single line, not including the end-of-line bytes.If the line was too long for the buffer then isPrefix is set and thebeginning of the line is returned. The rest of the line will be returnedfrom future calls. isPrefix will be false when returning the last fragmentof the line. The returned buffer is only valid until the next call toReadLine. ReadLine either returns a non-nil line or it returns an error,never both.
The text returned from ReadLine does not include the line end ("\r\n" or "\n").No indication or error is given if the input ends without a final line end.CallingReader.UnreadByte after ReadLine will always unread the last byte read(possibly a character belonging to the line end) even if that byte is notpart of the line returned by ReadLine.
func (*Reader)ReadRune¶
ReadRune reads a single UTF-8 encoded Unicode character and returns therune and its size in bytes. If the encoded rune is invalid, it consumes one byteand returns unicode.ReplacementChar (U+FFFD) with a size of 1.
func (*Reader)ReadSlice¶
ReadSlice reads until the first occurrence of delim in the input,returning a slice pointing at the bytes in the buffer.The bytes stop being valid at the next read.If ReadSlice encounters an error before finding a delimiter,it returns all the data in the buffer and the error itself (often io.EOF).ReadSlice fails with errorErrBufferFull if the buffer fills without a delim.Because the data returned from ReadSlice will be overwrittenby the next I/O operation, most clients should useReader.ReadBytes or ReadString instead.ReadSlice returns err != nil if and only if line does not end in delim.
func (*Reader)ReadString¶
ReadString reads until the first occurrence of delim in the input,returning a string containing the data up to and including the delimiter.If ReadString encounters an error before finding a delimiter,it returns the data read before the error and the error itself (often io.EOF).ReadString returns err != nil if and only if the returned data does not end indelim.For simple uses, a Scanner may be more convenient.
func (*Reader)Reset¶added ingo1.2
Reset discards any buffered data, resets all state, and switchesthe buffered reader to read from r.Calling Reset on the zero value ofReader initializes the internal bufferto the default size.Calling b.Reset(b) (that is, resetting aReader to itself) does nothing.
func (*Reader)UnreadByte¶
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 theReader was not a read operation. Notably,Reader.Peek,Reader.Discard, andReader.WriteTo are notconsidered read operations.
func (*Reader)UnreadRune¶
UnreadRune unreads the last rune. If the most recent method called ontheReader was not aReader.ReadRune,Reader.UnreadRune returns an error. (In thisregard it is stricter thanReader.UnreadByte, which will unread the last bytefrom any read operation.)
func (*Reader)WriteTo¶added ingo1.1
WriteTo implements io.WriterTo.This may make multiple calls to theReader.Read method of the underlyingReader.If the underlying reader supports theReader.WriteTo method,this calls the underlyingReader.WriteTo without buffering.
typeScanner¶added ingo1.1
type Scanner struct {// contains filtered or unexported fields}Scanner provides a convenient interface for reading data such asa file of newline-delimited lines of text. Successive calls totheScanner.Scan method will step through the 'tokens' of a file, skippingthe bytes between the tokens. The specification of a token isdefined by a split function of typeSplitFunc; the default splitfunction breaks the input into lines with line termination stripped.Scanner.Splitfunctions are defined in this package for scanning a file intolines, bytes, UTF-8-encoded runes, and space-delimited words. Theclient may instead provide a custom split function.
Scanning stops unrecoverably at EOF, the first I/O error, or a token toolarge to fit in theScanner.Buffer. When a scan stops, the reader may haveadvanced arbitrarily far past the last token. Programs that need morecontrol over error handling or large tokens, or must run sequential scanson a reader, should usebufio.Reader instead.
Example (Custom)¶
Use a Scanner with a custom split function (built by wrapping ScanWords) to validate32-bit decimal input.
package mainimport ("bufio""fmt""strconv""strings")func main() {// An artificial input source.const input = "1234 5678 1234567901234567890"scanner := bufio.NewScanner(strings.NewReader(input))// Create a custom split function by wrapping the existing ScanWords function.split := func(data []byte, atEOF bool) (advance int, token []byte, err error) {advance, token, err = bufio.ScanWords(data, atEOF)if err == nil && token != nil {_, err = strconv.ParseInt(string(token), 10, 32)}return}// Set the split function for the scanning operation.scanner.Split(split)// Validate the inputfor scanner.Scan() {fmt.Printf("%s\n", scanner.Text())}if err := scanner.Err(); err != nil {fmt.Printf("Invalid input: %s", err)}}Output:12345678Invalid input: strconv.ParseInt: parsing "1234567901234567890": value out of range
Example (EarlyStop)¶
Use a Scanner with a custom split function to parse a comma-separatedlist with an empty final value but stops at the token "STOP".
package mainimport ("bufio""bytes""fmt""os""strings")func main() {onComma := func(data []byte, atEOF bool) (advance int, token []byte, err error) {i := bytes.IndexByte(data, ',')if i == -1 {if !atEOF {return 0, nil, nil}// If we have reached the end, return the last token.return 0, data, bufio.ErrFinalToken}// If the token is "STOP", stop the scanning and ignore the rest.if string(data[:i]) == "STOP" {return i + 1, nil, bufio.ErrFinalToken}// Otherwise, return the token before the comma.return i + 1, data[:i], nil}const input = "1,2,STOP,4,"scanner := bufio.NewScanner(strings.NewReader(input))scanner.Split(onComma)for scanner.Scan() {fmt.Printf("Got a token %q\n", scanner.Text())}if err := scanner.Err(); err != nil {fmt.Fprintln(os.Stderr, "reading input:", err)}}Output:Got a token "1"Got a token "2"
Example (EmptyFinalToken)¶
Use a Scanner with a custom split function to parse a comma-separatedlist with an empty final value.
package mainimport ("bufio""fmt""os""strings")func main() {// Comma-separated list; last entry is empty.const input = "1,2,3,4,"scanner := bufio.NewScanner(strings.NewReader(input))// Define a split function that separates on commas.onComma := func(data []byte, atEOF bool) (advance int, token []byte, err error) {for i := 0; i < len(data); i++ {if data[i] == ',' {return i + 1, data[:i], nil}}if !atEOF {return 0, nil, nil}// There is one final token to be delivered, which may be the empty string.// Returning bufio.ErrFinalToken here tells Scan there are no more tokens after this// but does not trigger an error to be returned from Scan itself.return 0, data, bufio.ErrFinalToken}scanner.Split(onComma)// Scan.for scanner.Scan() {fmt.Printf("%q ", scanner.Text())}if err := scanner.Err(); err != nil {fmt.Fprintln(os.Stderr, "reading input:", err)}}Output:"1" "2" "3" "4" ""
Example (Lines)¶
The simplest use of a Scanner, to read standard input as a set of lines.
package mainimport ("bufio""fmt""os")func main() {scanner := bufio.NewScanner(os.Stdin)for scanner.Scan() {fmt.Println(scanner.Text()) // Println will add back the final '\n'}if err := scanner.Err(); err != nil {fmt.Fprintln(os.Stderr, "reading standard input:", err)}}Example (Words)¶
Use a Scanner to implement a simple word-count utility by scanning theinput as a sequence of space-delimited tokens.
package mainimport ("bufio""fmt""os""strings")func main() {// An artificial input source.const input = "Now is the winter of our discontent,\nMade glorious summer by this sun of York.\n"scanner := bufio.NewScanner(strings.NewReader(input))// Set the split function for the scanning operation.scanner.Split(bufio.ScanWords)// Count the words.count := 0for scanner.Scan() {count++}if err := scanner.Err(); err != nil {fmt.Fprintln(os.Stderr, "reading input:", err)}fmt.Printf("%d\n", count)}Output:15
funcNewScanner¶added ingo1.1
NewScanner returns a newScanner to read from r.The split function defaults toScanLines.
func (*Scanner)Buffer¶added ingo1.6
Buffer controls memory allocation by the Scanner.It sets the initial buffer to use when scanningand the maximum size of buffer that may be allocated during scanning.The contents of the buffer are ignored.
The maximum token size must be less than the larger of max and cap(buf).If max <= cap(buf),Scanner.Scan will use this buffer only and do no allocation.
By default,Scanner.Scan uses an internal buffer and sets themaximum token size toMaxScanTokenSize.
Buffer panics if it is called after scanning has started.
func (*Scanner)Bytes¶added ingo1.1
Bytes returns the most recent token generated by a call toScanner.Scan.The underlying array may point to data that will be overwrittenby a subsequent call to Scan. It does no allocation.
Example¶
Return the most recent call to Scan as a []byte.
package mainimport ("bufio""fmt""os""strings")func main() {scanner := bufio.NewScanner(strings.NewReader("gopher"))for scanner.Scan() {fmt.Println(len(scanner.Bytes()) == 6)}if err := scanner.Err(); err != nil {fmt.Fprintln(os.Stderr, "shouldn't see an error scanning a string")}}Output:true
func (*Scanner)Err¶added ingo1.1
Err returns the first non-EOF error that was encountered by theScanner.
func (*Scanner)Scan¶added ingo1.1
Scan advances theScanner to the next token, which will then beavailable through theScanner.Bytes orScanner.Text method. It returns false whenthere are no more tokens, either by reaching the end of the input or an error.After Scan returns false, theScanner.Err method will return any error thatoccurred during scanning, except that if it wasio.EOF,Scanner.Errwill return nil.Scan panics if the split function returns too many emptytokens without advancing the input. This is a common error mode forscanners.
func (*Scanner)Split¶added ingo1.1
Split sets the split function for theScanner.The default split function isScanLines.
Split panics if it is called after scanning has started.
func (*Scanner)Text¶added ingo1.1
Text returns the most recent token generated by a call toScanner.Scanas a newly allocated string holding its bytes.
typeSplitFunc¶added ingo1.1
SplitFunc is the signature of the split function used to tokenize theinput. The arguments are an initial substring of the remaining unprocesseddata and a flag, atEOF, that reports whether theReader has no more datato give. The return values are the number of bytes to advance the inputand the next token to return to the user, if any, plus an error, if any.
Scanning stops if the function returns an error, in which case some ofthe input may be discarded. If that error isErrFinalToken, scanningstops with no error. A non-nil token delivered withErrFinalTokenwill be the last token, and a nil token withErrFinalTokenimmediately stops the scanning.
Otherwise, theScanner advances the input. If the token is not nil,theScanner returns it to the user. If the token is nil, theScanner reads more data and continues scanning; if there is no moredata--if atEOF was true--theScanner returns. If the data does notyet hold a complete token, for instance if it has no newline whilescanning lines, aSplitFunc can return (0, nil, nil) to signal theScanner to read more data into the slice and try again with alonger slice starting at the same point in the input.
The function is never called with an empty data slice unless atEOFis true. If atEOF is true, however, data may be non-empty and,as always, holds unprocessed text.
typeWriter¶
type Writer struct {// contains filtered or unexported fields}Writer implements buffering for anio.Writer object.If an error occurs writing to aWriter, no more data will beaccepted and all subsequent writes, andWriter.Flush, will return the error.After all data has been written, the client should call theWriter.Flush method to guarantee all data has been forwarded tothe underlyingio.Writer.
Example¶
package mainimport ("bufio""fmt""os")func main() {w := bufio.NewWriter(os.Stdout)fmt.Fprint(w, "Hello, ")fmt.Fprint(w, "world!")w.Flush() // Don't forget to flush!}Output:Hello, world!
funcNewWriter¶
NewWriter returns a newWriter whose buffer has the default size.If the argument io.Writer is already aWriter with large enough buffer size,it returns the underlyingWriter.
funcNewWriterSize¶
NewWriterSize returns a newWriter whose buffer has at least the specifiedsize. If the argument io.Writer is already aWriter with large enoughsize, it returns the underlyingWriter.
func (*Writer)AvailableBuffer¶added ingo1.18
AvailableBuffer returns an empty buffer with b.Available() capacity.This buffer is intended to be appended to andpassed to an immediately succeedingWriter.Write call.The buffer is only valid until the next write operation on b.
Example¶
package mainimport ("bufio""os""strconv")func main() {w := bufio.NewWriter(os.Stdout)for _, i := range []int64{1, 2, 3, 4} {b := w.AvailableBuffer()b = strconv.AppendInt(b, i, 10)b = append(b, ' ')w.Write(b)}w.Flush()}Output:1 2 3 4
func (*Writer)Buffered¶
Buffered returns the number of bytes that have been written into the current buffer.
func (*Writer)ReadFrom¶added ingo1.1
ReadFrom implementsio.ReaderFrom. If the underlying writersupports the ReadFrom method, this calls the underlying ReadFrom.If there is buffered data and an underlying ReadFrom, this fillsthe buffer and writes it before calling ReadFrom.
Example¶
ExampleWriter_ReadFrom demonstrates how to use the ReadFrom method of Writer.
package mainimport ("bufio""bytes""fmt""strings")func main() {var buf bytes.Bufferwriter := bufio.NewWriter(&buf)data := "Hello, world!\nThis is a ReadFrom example."reader := strings.NewReader(data)n, err := writer.ReadFrom(reader)if err != nil {fmt.Println("ReadFrom Error:", err)return}if err = writer.Flush(); err != nil {fmt.Println("Flush Error:", err)return}fmt.Println("Bytes written:", n)fmt.Println("Buffer contents:", buf.String())}Output:Bytes written: 41Buffer contents: Hello, world!This is a ReadFrom example.
func (*Writer)Reset¶added ingo1.2
Reset discards any unflushed buffered data, clears any error, andresets b to write its output to w.Calling Reset on the zero value ofWriter initializes the internal bufferto the default size.Calling w.Reset(w) (that is, resetting aWriter to itself) does nothing.
func (*Writer)Write¶
Write writes the contents of p into the buffer.It returns the number of bytes written.If nn < len(p), it also returns an error explainingwhy the write is short.
Source Files