version: 1.10

package bufio

import "bufio"

Overview

Package bufio implements buffered I/O. It wraps an io.Reader or io.Writer
object, creating another object (Reader or Writer) that also implements the
interface but provides buffering and some help for textual I/O.

Index

Examples

Package files

bufio.go scan.go

Constants

  1. const (
  2.     // MaxScanTokenSize is the maximum size used to buffer a token
  3.     // unless the user provides an explicit buffer with Scan.Buffer.
  4.     // The actual maximum token size may be smaller as the buffer
  5.     // may need to include, for instance, a newline.
  6.     MaxScanTokenSize = 64 * 1024
  7. )

Variables

  1. var (
  2.     ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte")
  3.     ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune")
  4.     ErrBufferFull        = errors.New("bufio: buffer full")
  5.     ErrNegativeCount     = errors.New("bufio: negative count")
  6. )
  1. var (
  2.     ErrTooLong         = errors.New("bufio.Scanner: token too long")
  3.     ErrNegativeAdvance = errors.New("bufio.Scanner: SplitFunc returns negative advance count")
  4.     ErrAdvanceTooFar   = errors.New("bufio.Scanner: SplitFunc returns advance count beyond input")
  5. )

Errors returned by Scanner.

  1. var ErrFinalToken = errors.New("final token")

ErrFinalToken is a special sentinel error value. It is intended to be returned
by a Split function to indicate that the token being delivered with the error is
the last token and scanning should stop after this one. After ErrFinalToken is
received by Scan, scanning stops with no error. The value is useful to stop
processing early or when it is necessary to deliver a final empty token. One
could achieve the same behavior with a custom error value but providing one here
is tidier. See the emptyFinalToken example for a use of this value.

func ScanBytes

  1. func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error)

ScanBytes is a split function for a Scanner that returns each byte as a token.

func ScanLines

  1. func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error)

ScanLines is a split function for a Scanner that returns each line of text,
stripped of any trailing end-of-line marker. The returned line may be empty. The
end-of-line marker is one optional carriage return followed by 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 no newline.

func ScanRunes

  1. func ScanRunes(data []byte, atEOF bool) (advance int, token []byte, err error)

ScanRunes is a split function for a Scanner that returns each UTF-8-encoded rune
as a token. The sequence of runes returned is equivalent to that from a range
loop over the input as a string, which means that erroneous UTF-8 encodings
translate to U+FFFD = “\xef\xbf\xbd”. Because of the Scan interface, this makes
it impossible for the client to distinguish correctly encoded replacement runes
from encoding errors.

func ScanWords

  1. func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error)

ScanWords is a split function for a Scanner that returns each space-separated
word of text, with surrounding spaces deleted. It will never return an empty
string. The definition of space is set by unicode.IsSpace.

type ReadWriter

  1. type ReadWriter struct {
  2.     *Reader
  3.     *Writer
  4. }

ReadWriter stores pointers to a Reader and a Writer. It implements
io.ReadWriter.

func NewReadWriter

  1. func NewReadWriter(r *Reader, w *Writer) *ReadWriter

NewReadWriter allocates a new ReadWriter that dispatches to r and w.

type Reader

  1. type Reader struct {
  2.     // contains filtered or unexported fields
  3. }

Reader implements buffering for an io.Reader object.

func NewReader

  1. func NewReader(rd io.Reader) *Reader

NewReader returns a new Reader whose buffer has the default size.

func NewReaderSize

  1. func NewReaderSize(rd io.Reader, size int) *Reader

NewReaderSize returns a new Reader whose buffer has at least the specified size.
If the argument io.Reader is already a Reader with large enough size, it returns
the underlying Reader.

func (*Reader) Buffered

  1. func (b *Reader) Buffered() int

Buffered returns the number of bytes that can be read from the current buffer.

func (*Reader) Discard

  1. func (b *Reader) Discard(n int) (discarded int, err error)

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 without reading from the
underlying io.Reader.

func (*Reader) Peek

  1. func (b *Reader) Peek(n int) ([]byte, error)

Peek returns the next n bytes without advancing the reader. The bytes stop 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.

func (*Reader) Read

  1. func (b *Reader) Read(p []byte) (n int, err error)

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 underlying Reader, hence n may be less
than len(p). At EOF, the count will be zero and err will be io.EOF.

func (*Reader) ReadByte

  1. func (b *Reader) ReadByte() (byte, error)

ReadByte reads and returns a single byte. If no byte is available, returns an
error.

func (*Reader) ReadBytes

  1. func (b *Reader) ReadBytes(delim byte) ([]byte, error)

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 in delim. For simple uses, a Scanner
may be more convenient.

func (*Reader) ReadLine

  1. func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error)

ReadLine is a low-level line-reading primitive. Most callers should use
ReadBytes(‘\n’) or ReadString(‘\n’) instead or use a Scanner.

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 the beginning of
the line is returned. The rest of the line will be returned from future calls.
isPrefix will be false when returning the last fragment of the line. The
returned buffer is only valid until the next call to ReadLine. 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.
Calling UnreadByte after ReadLine will always unread the last byte read
(possibly a character belonging to the line end) even if that byte is not part
of the line returned by ReadLine.

func (*Reader) ReadRune

  1. func (b *Reader) ReadRune() (r rune, size int, err error)

ReadRune reads a single UTF-8 encoded Unicode character and returns the rune and
its size in bytes. If the encoded rune is invalid, it consumes one byte and
returns unicode.ReplacementChar (U+FFFD) with a size of 1.

func (*Reader) ReadSlice

  1. func (b *Reader) ReadSlice(delim byte) (line []byte, err error)

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 error ErrBufferFull if the buffer fills without a delim.
Because the data returned from ReadSlice will be overwritten by the next I/O
operation, most clients should use ReadBytes or ReadString instead. ReadSlice
returns err != nil if and only if line does not end in delim.

func (*Reader) ReadString

  1. func (b *Reader) ReadString(delim byte) (string, error)

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 in delim. For simple uses, a Scanner
may be more convenient.

func (*Reader) Reset

  1. func (b *Reader) Reset(r io.Reader)

Reset discards any buffered data, resets all state, and switches the buffered
reader to read from r.

func (*Reader) Size

  1. func (r *Reader) Size() int

Size returns the size of the underlying buffer in bytes.

func (*Reader) UnreadByte

  1. func (b *Reader) UnreadByte() error

UnreadByte unreads the last byte. Only the most recently read byte can be
unread.

func (*Reader) UnreadRune

  1. func (b *Reader) UnreadRune() error

UnreadRune unreads the last rune. If the most recent read operation on the
buffer 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 (*Reader) WriteTo

  1. func (b *Reader) WriteTo(w io.Writer) (n int64, err error)

WriteTo implements io.WriterTo. This may make multiple calls to the Read method
of the underlying Reader.

type Scanner

  1. type Scanner struct {
  2.     // contains filtered or unexported fields
  3. }

Scanner provides a convenient interface for reading data such as a file of
newline-delimited lines of text. Successive calls to the Scan method will step
through the ‘tokens’ of a file, skipping the bytes between the tokens. The
specification of a token is defined by a split function of type SplitFunc; the
default split function breaks the input into lines with line termination
stripped. Split functions are defined in this package for scanning a file into
lines, bytes, UTF-8-encoded runes, and space-delimited words. The client may
instead provide a custom split function.

Scanning stops unrecoverably at EOF, the first I/O error, or a token too large
to fit in the buffer. When a scan stops, the reader may have advanced
arbitrarily far past the last token. Programs that need more control over error
handling or large tokens, or must run sequential scans on a reader, should use
bufio.Reader instead.


Example:

  1. // An artificial input source.
  2. const input = "1234 5678 1234567901234567890"
  3. scanner := bufio.NewScanner(strings.NewReader(input))
  4. // Create a custom split function by wrapping the existing ScanWords function.
  5. split := func(data []byte, atEOF bool) (advance int, token []byte, err error) {
  6.     advance, token, err = bufio.ScanWords(data, atEOF)
  7.     if err == nil && token != nil {
  8.         _, err = strconv.ParseInt(string(token), 10, 32)
  9.     }
  10.     return
  11. }
  12. // Set the split function for the scanning operation.
  13. scanner.Split(split)
  14. // Validate the input
  15. for scanner.Scan() {
  16.     fmt.Printf("%s\n", scanner.Text())
  17. }
  19. if err := scanner.Err(); err != nil {
  20.     fmt.Printf("Invalid input: %s", err)
  21. }
  22. // Output:
  23. // 1234
  24. // 5678
  25. // Invalid input: strconv.ParseInt: parsing "1234567901234567890": value out of range


Example:

  1. // Comma-separated list; last entry is empty.
  2. const input = "1,2,3,4,"
  3. scanner := bufio.NewScanner(strings.NewReader(input))
  4. // Define a split function that separates on commas.
  5. onComma := func(data []byte, atEOF bool) (advance int, token []byte, err error) {
  6.     for i := 0; i < len(data); i++ {
  7.         if data[i] == ',' {
  8.             return i + 1, data[:i], nil
  9.         }
  10.     }
  11.     // There is one final token to be delivered, which may be the empty string.
  12.     // Returning bufio.ErrFinalToken here tells Scan there are no more tokens after this
  13.     // but does not trigger an error to be returned from Scan itself.
  14.     return 0, data, bufio.ErrFinalToken
  15. }
  16. scanner.Split(onComma)
  17. // Scan.
  18. for scanner.Scan() {
  19.     fmt.Printf("%q ", scanner.Text())
  20. }
  21. if err := scanner.Err(); err != nil {
  22.     fmt.Fprintln(os.Stderr, "reading input:", err)
  23. }
  24. // Output: "1" "2" "3" "4" ""


Example:

  1. scanner := bufio.NewScanner(os.Stdin)
  2. for scanner.Scan() {
  3.     fmt.Println(scanner.Text()) // Println will add back the final '\n'
  4. }
  5. if err := scanner.Err(); err != nil {
  6.     fmt.Fprintln(os.Stderr, "reading standard input:", err)
  7. }


Example:

  1. // An artificial input source.
  2. const input = "Now is the winter of our discontent,\nMade glorious summer by this sun of York.\n"
  3. scanner := bufio.NewScanner(strings.NewReader(input))
  4. // Set the split function for the scanning operation.
  5. scanner.Split(bufio.ScanWords)
  6. // Count the words.
  7. count := 0
  8. for scanner.Scan() {
  9.     count++
  10. }
  11. if err := scanner.Err(); err != nil {
  12.     fmt.Fprintln(os.Stderr, "reading input:", err)
  13. }
  14. fmt.Printf("%d\n", count)
  15. // Output: 15

func NewScanner

  1. func NewScanner(r io.Reader) *Scanner

NewScanner returns a new Scanner to read from r. The split function defaults to
ScanLines.

func (*Scanner) Buffer

  1. func (s *Scanner) Buffer(buf []byte, max int)

Buffer sets the initial buffer to use when scanning and the maximum size of
buffer that may be allocated during scanning. The maximum token size is the
larger of max and cap(buf). If max <= cap(buf), Scan will use this buffer only
and do no allocation.

By default, Scan uses an internal buffer and sets the maximum token size to
MaxScanTokenSize.

Buffer panics if it is called after scanning has started.

func (*Scanner) Bytes

  1. func (s *Scanner) Bytes() []byte

Bytes returns the most recent token generated by a call to Scan. The underlying
array may point to data that will be overwritten by a subsequent call to Scan.
It does no allocation.

func (*Scanner) Err

  1. func (s *Scanner) Err() error

Err returns the first non-EOF error that was encountered by the Scanner.

func (*Scanner) Scan

  1. func (s *Scanner) Scan() bool

Scan advances the Scanner to the next token, which will then be available
through the Bytes or Text method. It returns false when the scan stops, either
by reaching the end of the input or an error. After Scan returns false, the Err
method will return any error that occurred during scanning, except that if it
was io.EOF, Err will return nil. Scan panics if the split function returns too
many empty tokens without advancing the input. This is a common error mode for
scanners.

func (*Scanner) Split

  1. func (s *Scanner) Split(split SplitFunc)

Split sets the split function for the Scanner. The default split function is
ScanLines.

Split panics if it is called after scanning has started.

func (*Scanner) Text

  1. func (s *Scanner) Text() string

Text returns the most recent token generated by a call to Scan as a newly
allocated string holding its bytes.

type SplitFunc

  1. type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)

SplitFunc is the signature of the split function used to tokenize the input. The
arguments are an initial substring of the remaining unprocessed data and a flag,
atEOF, that reports whether the Reader has no more data to give. The return
values are the number of bytes to advance the input and the next token to return
to the user, plus an error, if any. If the data does not yet hold a complete
token, for instance if it has no newline while scanning lines, SplitFunc can
return (0, nil, nil) to signal the Scanner to read more data into the slice and
try again with a longer slice starting at the same point in the input.

If the returned error is non-nil, scanning stops and the error is returned to
the client.

The function is never called with an empty data slice unless atEOF is true. If
atEOF is true, however, data may be non-empty and, as always, holds unprocessed
text.

type Writer

  1. type Writer struct {
  2.     // contains filtered or unexported fields
  3. }

Writer implements buffering for an io.Writer object. If an error occurs writing
to a Writer, no more data will be accepted and all subsequent writes, and Flush,
will return the error. After all data has been written, the client should call
the Flush method to guarantee all data has been forwarded to the underlying
io.Writer.


Example:

  1. w := bufio.NewWriter(os.Stdout)
  2. fmt.Fprint(w, "Hello, ")
  3. fmt.Fprint(w, "world!")
  4. w.Flush() // Don't forget to flush!
  5. // Output: Hello, world!

func NewWriter

  1. func NewWriter(w io.Writer) *Writer

NewWriter returns a new Writer whose buffer has the default size.

func NewWriterSize

  1. func NewWriterSize(w io.Writer, size int) *Writer

NewWriterSize returns a new Writer whose buffer has at least the specified size.
If the argument io.Writer is already a Writer with large enough size, it returns
the underlying Writer.

func (*Writer) Available

  1. func (b *Writer) Available() int

Available returns how many bytes are unused in the buffer.

func (*Writer) Buffered

  1. func (b *Writer) Buffered() int

Buffered returns the number of bytes that have been written into the current
buffer.

func (*Writer) Flush

  1. func (b *Writer) Flush() error

Flush writes any buffered data to the underlying io.Writer.

func (*Writer) ReadFrom

  1. func (b *Writer) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom implements io.ReaderFrom.

func (*Writer) Reset

  1. func (b *Writer) Reset(w io.Writer)

Reset discards any unflushed buffered data, clears any error, and resets b to
write its output to w.

func (*Writer) Size

  1. func (b *Writer) Size() int

Size returns the size of the underlying buffer in bytes.

func (*Writer) Write

  1. func (b *Writer) Write(p []byte) (nn int, err error)

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 explaining why the write is
short.

func (*Writer) WriteByte

  1. func (b *Writer) WriteByte(c byte) error

WriteByte writes a single byte.

func (*Writer) WriteRune

  1. func (b *Writer) WriteRune(r rune) (size int, err error)

WriteRune writes a single Unicode code point, returning the number of bytes
written and any error.

func (*Writer) WriteString

  1. func (b *Writer) WriteString(s string) (int, error)

WriteString writes a string. It returns the number of bytes written. If the
count is less than len(s), it also returns an error explaining why the write is
short.