bufio
import "bufio"
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.
Go 1.26.1
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 th...
bufio/scan.go:82
Variables
var (
ErrTooLong = errors.New("bufio.Scanner: token too long")
ErrNegativeAdvance = errors.New("bufio.Scanner: SplitFunc returns negative advance count")
ErrAdvanceTooFar = errors.New(...Errors returned by Scanner.
bufio/scan.go:73
var (
ErrTooLong = errors.New("bufio.Scanner: token too long")
ErrNegativeAdvance = errors.New("bufio.Scanner: SplitFunc returns negative advance count")
ErrAdvanceTooFar = errors.New(...Errors returned by Scanner.
bufio/scan.go:74
var (
ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte")
ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune")
ErrBufferFull = errors.New("bufio: buffer...bufio/bufio.go:25
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 scanning should stop with 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 to deliver a final empty token (which is different from a nil token). One could achieve the same behavior with a custom error value but providing one here is tidier. See the emptyFinalT...
bufio/scan.go:128
var (
ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte")
ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune")
ErrBufferFull = errors.New("bufio: buffer...bufio/bufio.go:23
var (
ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte")
ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune")
ErrBufferFull = errors.New("bufio: buffer...bufio/bufio.go:24
var (
ErrTooLong = errors.New("bufio.Scanner: token too long")
ErrNegativeAdvance = errors.New("bufio.Scanner: SplitFunc returns negative advance count")
ErrAdvanceTooFar = errors.New(...Errors returned by Scanner.
bufio/scan.go:72
var (
ErrInvalidUnreadByte = errors.New("bufio: invalid use of UnreadByte")
ErrInvalidUnreadRune = errors.New("bufio: invalid use of UnreadRune")
ErrBufferFull = errors.New("bufio: buffer...bufio/bufio.go:26
var (
ErrTooLong = errors.New("bufio.Scanner: token too long")
ErrNegativeAdvance = errors.New("bufio.Scanner: SplitFunc returns negative advance count")
ErrAdvanceTooFar = errors.New(...Errors returned by Scanner.
bufio/scan.go:71
Functions
func NewReader(rd io.Reader) *Reader
NewReader returns a new [Reader] whose buffer has the default size.
bufio/bufio.go:62
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].
bufio/bufio.go:50
func NewReadWriter(r *Reader, w *Writer) *ReadWriter
NewReadWriter allocates a new [ReadWriter] that dispatches to r and w.
bufio/bufio.go:840
func NewScanner(r io.Reader) *Scanner
NewScanner returns a new [Scanner] to read from r. The split function defaults to [ScanLines].
bufio/scan.go:89
func NewWriter(w io.Writer) *Writer
NewWriter returns a new [Writer] whose buffer has the default size. If the argument io.Writer is already a [Writer] with large enough buffer size, it returns the underlying [Writer].
bufio/bufio.go:607
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].
bufio/bufio.go:589
func ScanBytes(data []byte, atEOF bool) (int, []byte, error)
ScanBytes is a split function for a [Scanner] that returns each byte as a token.
bufio/scan.go:297
func ScanLines(data []byte, atEOF bool) (int, []byte, 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.
bufio/scan.go:358
func ScanRunes(data []byte, atEOF bool) (int, []byte, 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.
bufio/scan.go:312
func ScanWords(data []byte, atEOF bool) (int, []byte, 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.
bufio/scan.go:403
Types
type Reader struct {
// contains filtered or unexported fields
}Reader implements buffering for an io.Reader object. A new Reader is created by calling [NewReader] or [NewReaderSize]; alternatively the zero value of a Reader may be used after calling [Reset] on it.
bufio/bufio.go:35
func (b *Reader) Buffered() int
Buffered returns the number of bytes that can be read from the current buffer.
bufio/bufio.go:336
func (b *Reader) Discard(n int) (int, 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.
bufio/bufio.go:177
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 necessary, Peek will read more bytes into the buffer in order to make n bytes available. 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 [Reader.UnreadByte] or [Reader.UnreadRune] call from succeeding until the next read operation.
bufio/bufio.go:143
func (b *Reader) Read(p []byte) (int, 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). To read exactly len(p) bytes, use io.ReadFull(b, p). If the underlying [Reader] can return a non-zero count with io.EOF, then this Read method can do so as well; see the [io.Reader] docs.
bufio/bufio.go:216
func (b *Reader) ReadByte() (byte, error)
ReadByte reads and returns a single byte. If no byte is available, returns an error.
bufio/bufio.go:267
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.
bufio/bufio.go:478
func (b *Reader) ReadLine() ([]byte, bool, error)
ReadLine is a low-level line-reading primitive. Most callers should use [Reader.ReadBytes]('\n') or [Reader.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 u...
bufio/bufio.go:405
func (b *Reader) ReadRune() (rune, int, 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.
bufio/bufio.go:306
func (b *Reader) ReadSlice(delim byte) ([]byte, 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 [Re...
bufio/bufio.go:348
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.
bufio/bufio.go:498
func (b *Reader) Reset(r io.Reader)
Reset discards any buffered data, resets all state, and switches the buffered reader to read from r. Calling Reset on the zero value of [Reader] initializes the internal buffer to the default size. Calling b.Reset(b) (that is, resetting a [Reader] to itself) does nothing.
bufio/bufio.go:74
func (b *Reader) Size() int
Size returns the size of the underlying buffer in bytes.
bufio/bufio.go:67
func (b *Reader) UnreadByte() error
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, [Reader.Peek], [Reader.Discard], and [Reader.WriteTo] are not considered read operations.
bufio/bufio.go:286
func (b *Reader) UnreadRune() error
UnreadRune unreads the last rune. If the most recent method called on the [Reader] was not a [Reader.ReadRune], [Reader.UnreadRune] returns an error. (In this regard it is stricter than [Reader.UnreadByte], which will unread the last byte from any read operation.)
bufio/bufio.go:325
func (b *Reader) WriteTo(w io.Writer) (int64, error)
WriteTo implements io.WriterTo. This may make multiple calls to the [Reader.Read] method of the underlying [Reader]. If the underlying reader supports the [Reader.WriteTo] method, this calls the underlying [Reader.WriteTo] without buffering.
bufio/bufio.go:515
type ReadWriter struct {
*Reader
*Writer
}ReadWriter stores pointers to a [Reader] and a [Writer]. It implements [io.ReadWriter].
bufio/bufio.go:834
type Scanner struct {
// contains filtered or unexported fields
}Scanner provides a convenient interface for reading data such as a file of newline-delimited lines of text. Successive calls to the [Scanner.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. [Scanner.Split] functions are defined in this package for scanning a file into lines, bytes, U...
bufio/scan.go:29
func (s *Scanner) Buffer(buf []byte, max int)
Buffer controls memory allocation by the Scanner. It sets the initial buffer to use when scanning and 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 the maximum token size to [MaxScanTokenSize]. Buffer panics if it is c...
bufio/scan.go:275
func (s *Scanner) Bytes() []byte
Bytes returns the most recent token generated by a call to [Scanner.Scan]. The underlying array may point to data that will be overwritten by a subsequent call to Scan. It does no allocation.
bufio/scan.go:108
func (s *Scanner) Err() error
Err returns the first non-EOF error that was encountered by the [Scanner].
bufio/scan.go:98
func (s *Scanner) Scan() bool
Scan advances the [Scanner] to the next token, which will then be available through the [Scanner.Bytes] or [Scanner.Text] method. It returns false when there are no more tokens, either by reaching the end of the input or an error. After Scan returns false, the [Scanner.Err] method will return any error that occurred during scanning, except that if it was [io.EOF], [Scanner.Err] will return nil. Scan panics if the split function returns too many empty tokens without advancing the input. This i...
bufio/scan.go:139
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.
bufio/scan.go:287
func (s *Scanner) Text() string
Text returns the most recent token generated by a call to [Scanner.Scan] as a newly allocated string holding its bytes.
bufio/scan.go:114
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, if any, plus an error, if any. Scanning stops if the function returns an error, in which case some of the input may be discarded. If that error is [ErrFinalToken]...
bufio/scan.go:67
type Writer struct {
// contains filtered or unexported fields
}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 [Writer.Flush], will return the error. After all data has been written, the client should call the [Writer.Flush] method to guarantee all data has been forwarded to the underlying [io.Writer].
bufio/bufio.go:579
func (b *Writer) Available() int
Available returns how many bytes are unused in the buffer.
bufio/bufio.go:659
func (b *Writer) AvailableBuffer() []byte
AvailableBuffer returns an empty buffer with b.Available() capacity. This buffer is intended to be appended to and passed to an immediately succeeding [Writer.Write] call. The buffer is only valid until the next write operation on b.
bufio/bufio.go:665
func (b *Writer) Buffered() int
Buffered returns the number of bytes that have been written into the current buffer.
bufio/bufio.go:670
func (b *Writer) Flush() error
Flush writes any buffered data to the underlying [io.Writer].
bufio/bufio.go:635
func (b *Writer) ReadFrom(r io.Reader) (int64, error)
ReadFrom implements [io.ReaderFrom]. If the underlying writer supports the ReadFrom method, this calls the underlying ReadFrom. If there is buffered data and an underlying ReadFrom, this fills the buffer and writes it before calling ReadFrom.
bufio/bufio.go:784
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. Calling Reset on the zero value of [Writer] initializes the internal buffer to the default size. Calling w.Reset(w) (that is, resetting a [Writer] to itself) does nothing.
bufio/bufio.go:619
func (b *Writer) Size() int
Size returns the size of the underlying buffer in bytes.
bufio/bufio.go:612
func (b *Writer) Write(p []byte) (int, 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.
bufio/bufio.go:676
func (b *Writer) WriteByte(c byte) error
WriteByte writes a single byte.
bufio/bufio.go:701
func (b *Writer) WriteRune(r rune) (int, error)
WriteRune writes a single Unicode code point, returning the number of bytes written and any error.
bufio/bufio.go:715
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.
bufio/bufio.go:747