Пакет bufio
Обзор
Пакет bufio реализует буферизованный ввод-вывод. Он оборачивает объект io.Reader или io.Writer, создавая другой объект (Reader или Writer), который также реализует интерфейс, но предоставляет буферизацию и некоторую помощь для текстового ввода-вывода.
Индекс
Примеры
Файлы пакета
bufio.go scan.go
Константы
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
) Переменные
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")
) Возвращаемые Scanner ошибки.
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")
) ErrFinalToken — специальное значение ошибки-маяка. Предполагается, что функция Split должна возвращать его, чтобы указать, что сканирование должно быть остановлено без ошибки. Если возвращаемый с этой ошибкой токен не равен nil, токен является последним токеном.
Это значение полезно для ранней остановки обработки или когда необходимо передать финальный пустой токен (который отличается от nil токена). Можно было бы достичь такого же поведения с пользовательским значением ошибки, но предоставление его здесь более удобно. См. пример emptyFinalToken для использования этого значения.
var ErrFinalToken = errors.New("final token") func ScanBytes 1.1
func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error)
ScanBytes — функция разделения для Scanner, которая возвращает каждый байт как токен.
func ScanLines 1.1
func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error)
ScanLines — функция разделения для Scanner, которая возвращает каждую строку текста, очищенную от любого завершающего маркера конца строки. Возвращаемая строка может быть пустой. Маркер конца строки — это один необязательный возврат каретки, за которым следует один обязательный символ новой строки. В нотации регулярных выражений это `\r?\n`. Последняя непустая строка входных данных будет возвращена, даже если она не содержит символ новой строки.
func ScanRunes 1.1
func ScanRunes(data []byte, atEOF bool) (advance int, token []byte, err error)
ScanRunes — функция разделения для Scanner, которая возвращает каждый UTF-8-кодированный символ как токен. Последовательность символов, возвращаемых, эквивалентна последовательности из цикла range по входу как строке, что означает, что ошибочные UTF-8-кодировки преобразуются в U+FFFD = "\xef\xbf\xbd". Из-за интерфейса Scan клиент не может правильно отличить правильно закодированные символы-замены от ошибок кодирования.
func ScanWords 1.1
func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error)
ScanWords — функция разделения для Scanner, которая возвращает каждое разделенное пробелами слово текста, с удаленными окружающими пробелами. Она никогда не вернет пустую строку. Определение пробела задается функцией unicode.IsSpace.
тип ReadWriter
ReadWriter хранит указатели на Reader и Writer. Он реализует io.ReadWriter.
type ReadWriter struct {
*Reader
*Writer
}
func NewReadWriter
func NewReadWriter(r *Reader, w *Writer) *ReadWriter
NewReadWriter выделяет новый ReadWriter, который обращается к r и w.
тип Reader
Reader реализует буферизацию для объекта io.Reader.
type Reader struct {
// contains filtered or unexported fields
}
func NewReader
func NewReader(rd io.Reader) *Reader
NewReader возвращает новый Reader с буфером по умолчанию.
func NewReaderSize
func NewReaderSize(rd io.Reader, size int) *Reader
NewReaderSize возвращает новый Reader, чей буфер имеет как минимум указанный размер. Если аргумент io.Reader уже является Reader с достаточно большим размером, он возвращает базовый Reader.
func (*Reader) Buffered
func (b *Reader) Buffered() int
Buffered возвращает количество байтов, которые можно прочитать из текущего буфера.
func (*Reader) Discard 1.5
func (b *Reader) Discard(n int) (discarded int, err error)
Discard пропускает следующие n байтов, возвращая количество пропущенных байтов.
Если Discard пропускает меньше n байтов, он также возвращает ошибку. Если 0 <= n <= b.Buffered(), Discard гарантированно выполнится без чтения из базового io.Reader.
func (*Reader) Peek
func (b *Reader) Peek(n int) ([]byte, error)
Peek возвращает следующие n байтов без перемещения чтения. Байты перестают быть валидными при следующем вызове чтения. Если Peek возвращает меньше n байтов, он также возвращает ошибку, объясняющую, почему чтение сократилось. Ошибка — ErrBufferFull, если n больше размера буфера b.
Вызов Peek предотвращает успешный вызов Reader.UnreadByte или Reader.UnreadRune до следующей операции чтения.
func (*Reader) Read
func (b *Reader) Read(p []byte) (n int, err error)
Read считывает данные в p. Возвращает количество считанных байтов в p. Байты берутся из не более чем одного чтения из базового Reader, поэтому n может быть меньше len(p). Чтобы прочитать ровно len(p) байтов, используйте io.ReadFull(b, p). Если базовый Reader может вернуть ненулевой счет с io.EOF, то этот метод Read также может это сделать; см. документацию io.Reader.
func (*Reader) ReadByte
func (b *Reader) ReadByte() (byte, error)
ReadByte считывает и возвращает один байт. Если байт недоступен, возвращает ошибку.
func (*Reader) ReadBytes
func (b *Reader) ReadBytes(delim byte) ([]byte, error)
ReadBytes читает до первого вхождения delim во входные данные, возвращая срез, содержащий данные до и включая разделитель. Если ReadBytes встречает ошибку до нахождения разделителя, он возвращает данные, прочитанные до ошибки, и саму ошибку (часто io.EOF). ReadBytes возвращает err != nil тогда и только тогда, когда возвращаемые данные не заканчиваются на delim. Для простых случаев использования Scanner может быть удобнее.
func (*Reader) ReadLine
func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error)
ReadLine — низкоуровневая функция чтения строк. Большинству вызывающих функций следует использовать Reader.ReadBytes('\n') или Reader.ReadString('\n') вместо этого или использовать Scanner.
ReadLine пытается вернуть одну строку, не включая байты конца строки. Если строка была слишком длинной для буфера, то isPrefix устанавливается, и возвращается начало строки. Остальная часть строки будет возвращена при будущих вызовах. isPrefix будет false при возвращении последнего фрагмента строки. Возвращаемый буфер действителен только до следующего вызова ReadLine. ReadLine либо возвращает не nil строку, либо возвращает ошибку, но никогда не оба.
Текст, возвращаемый из ReadLine, не включает символ конца строки ("\r\n" или "\n"). Не выдаётся никакого сообщения или ошибки, если входная последовательность завершается без конечного символа конца строки. Вызов Reader.UnreadByte после ReadLine всегда вернёт последний прочитанный байт (возможно, символ, принадлежащий концу строки), даже если этот байт не является частью строки, возвращённой ReadLine.
func (*Reader) ReadRune
func (b *Reader) ReadRune() (r rune, size int, err error)
ReadRune считывает один символ Юникода, закодированный в UTF-8, и возвращает символ и его размер в байтах. Если закодированный символ некорректен, он потребляет один байт и возвращает unicode.ReplacementChar (U+FFFD) с размером 1.
func (*Reader) ReadSlice
func (b *Reader) ReadSlice(delim byte) (line []byte, err error)
ReadSlice считывает данные до первого вхождения delim во входных данных, возвращая срез, указывающий на байты в буфере. Байты перестают быть действительными при следующем чтении. Если ReadSlice обнаруживает ошибку до нахождения разделителя, он возвращает все данные в буфере и саму ошибку (часто io.EOF). ReadSlice завершается с ошибкой ErrBufferFull, если буфер заполняется без разделителя. Поскольку данные, возвращаемые ReadSlice, будут перезаписаны следующей операцией ввода-вывода, большинство клиентов должны использовать Reader.ReadBytes или ReadString вместо него. ReadSlice возвращает err != nil тогда и только тогда, когда строка не заканчивается delim.
func (*Reader) ReadString
func (b *Reader) ReadString(delim byte) (string, error)
ReadString считывает данные до первого вхождения delim во входных данных, возвращая строку, содержащую данные до и включая разделитель. Если ReadString обнаруживает ошибку до нахождения разделителя, он возвращает данные, прочитанные до ошибки, и саму ошибку (часто io.EOF). ReadString возвращает err != nil только тогда, когда возвращаемые данные не заканчиваются delim. Для простых случаев использования Scanner может быть более удобным.
func (*Reader) Reset 1.2
func (b *Reader) Reset(r io.Reader)
Reset отбрасывает все данные в буфере, сбрасывает все состояния и переключает буферизованный ридер на чтение из r. Вызов Reset для нулевого значения Reader инициализирует внутренний буфер размером по умолчанию. Вызов b.Reset(b) (то есть сброс Reader к самому себе) ничего не делает.
func (*Reader) Size 1.10
func (b *Reader) Size() int
Size возвращает размер базового буфера в байтах.
func (*Reader) UnreadByte
func (b *Reader) UnreadByte() error
UnreadByte отменяет чтение последнего байта. Можно отменить только самый последний прочитанный байт.
UnreadByte возвращает ошибку, если последним методом, вызванным на Reader, не была операция чтения. Отметим, что Reader.Peek, Reader.Discard и Reader.WriteTo не считаются операциями чтения.
func (*Reader) UnreadRune
func (b *Reader) UnreadRune() error
UnreadRune отменяет чтение последнего символа. Если последним методом, вызванным на Reader, не был Reader.ReadRune, Reader.UnreadRune возвращает ошибку. (В этом отношении он более строг, чем Reader.UnreadByte, который отменяет чтение последнего байта из любой операции чтения.)
func (*Reader) WriteTo 1.1
func (b *Reader) WriteTo(w io.Writer) (n int64, err error)
WriteTo реализует io.WriterTo. Это может вызвать несколько вызовов метода Reader.Read базового Reader. Если базовый ридер поддерживает метод Reader.WriteTo, это вызов базового Reader.WriteTo без буферизации.
type Scanner 1.1
Scanner предоставляет удобный интерфейс для чтения данных, таких как файл с текстовыми строками, разделёнными символами новой строки. Последовательные вызовы метода Scanner.Scan будут проходить по 'токенам' файла, пропуская байты между ними. Определение токена определяется функцией split типа SplitFunc; функция по умолчанию разделяет входные данные на строки с удалёнными символами завершения строки. Scanner.Split функции определены в этом пакете для сканирования файла на строки, байты, символы Юникода, закодированные в UTF-8, и слова, разделённые пробелами. Клиент может вместо этого предоставить пользовательскую функцию split.
Сканирование останавливается непреодолимо при EOF, первой ошибке ввода-вывода или токенах, слишком больших для размещения в Scanner.Buffer. Когда сканирование останавливается, ридер может продвинуться произвольно далеко за пределы последнего токена. Программы, которым нужен больший контроль над обработкой ошибок или большими токенами, или которым требуется выполнять последовательные сканирования на ридере, должны использовать bufio.Reader вместо этого.
type Scanner struct {
// contains filtered or unexported fields
}
Пример (Пользовательский)
Используйте Scanner с пользовательской функцией split (созданной с помощью обёртки ScanWords) для проверки 32-битного десятичного ввода.
Код:
// 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 input
for scanner.Scan() {
fmt.Printf("%s\n", scanner.Text())
}
if err := scanner.Err(); err != nil {
fmt.Printf("Invalid input: %s", err)
}
Вывод:
1234 5678 Invalid input: strconv.ParseInt: parsing "1234567901234567890": value out of range
Пример (EarlyStop)
Используйте Scanner с пользовательской функцией split для разбора списка, разделённого запятыми, с пустым конечным значением, но останавливаетесь на токене "STOP".
Код:
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)
}
Вывод:
Got a token "1" Got a token "2"
Пример (EmptyFinalToken)
Используйте Scanner с пользовательской функцией split для разбора списка, разделённого запятыми, с пустым конечным значением.
Код:
// 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)
}
Вывод:
"1" "2" "3" "4" ""
Пример (Строки)
Самое простое использование Scanner, для чтения стандартного ввода как набора строк.
Код:
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)
}
Пример (Слова)
Используйте Scanner для реализации простой утилиты подсчёта слов, сканируя входные данные как последовательность токенов, разделённых пробелами.
Код:
// 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 := 0
for scanner.Scan() {
count++
}
if err := scanner.Err(); err != nil {
fmt.Fprintln(os.Stderr, "reading input:", err)
}
fmt.Printf("%d\n", count)
Вывод:
15
func NewScanner 1.1
func NewScanner(r io.Reader) *Scanner
NewScanner возвращает новый Scanner для чтения из r. Функция split по умолчанию - ScanLines.
func (*Scanner) Buffer 1.6
func (s *Scanner) Buffer(buf []byte, max int)
Buffer устанавливает начальный буфер для использования при сканировании и максимальный размер буфера, который может быть выделен во время сканирования. Максимальный размер токена должен быть меньше большего из max и cap(buf). Если max <= cap(buf), Scanner.Scan будет использовать только этот буфер и не выполнять выделение.
По умолчанию Scanner.Scan использует внутренний буфер и устанавливает максимальный размер токена в MaxScanTokenSize.
Buffer вызывает панику, если он вызван после начала сканирования.
func (*Scanner) Bytes 1.1
func (s *Scanner) Bytes() []byte
Bytes возвращает последний токен, сгенерированный вызовом Scanner.Scan. Базовый массив может указывать на данные, которые будут перезаписаны последующим вызовом Scan. Он не выполняет выделение.
Пример
Возвращает последний вызов Scan как []byte.
Код:
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")
}
Вывод:
true
func (*Scanner) Err 1.1
func (s *Scanner) Err() error
Err возвращает первую ошибку, отличную от EOF, которая была встречена Scanner.
func (*Scanner) Scan 1.1
func (s *Scanner) Scan() bool
Scan перемещает Scanner к следующему токену, который затем будет доступен через метод Scanner.Bytes или Scanner.Text. Он возвращает false, когда больше нет токенов, либо из-за достижения конца ввода, либо из-за ошибки. После того как Scan вернул false, метод Scanner.Err вернёт любую ошибку, произошедшую во время сканирования, за исключением случая, когда это была io.EOF, в этом случае Scanner.Err вернёт nil. Scan вызывает панику, если функция split возвращает слишком много пустых токенов без продвижения ввода. Это распространённый режим работы для сканеров.
func (*Scanner) Split 1.1
func (s *Scanner) Split(split SplitFunc)
Split устанавливает функцию split для Scanner. Функция split по умолчанию - ScanLines.
Split вызывает панику, если он вызван после начала сканирования.
func (*Scanner) Text 1.1
func (s *Scanner) Text() string
Text возвращает последний токен, сгенерированный вызовом Scanner.Scan, как новую строку, содержащую его байты.
type SplitFunc 1.1
SplitFunc — это сигнатура функции split, используемой для разбиения входных данных на токены. Аргументами являются начальная подстрока оставшихся необработанных данных и флаг atEOF, сообщающий, есть ли у Reader больше данных для передачи. Возвращаемые значения — это количество байтов для продвижения входных данных и следующий токен для возврата пользователю, если таковой имеется, а также ошибка, если таковая имеется.
Сканирование останавливается, если функция возвращает ошибку, в этом случае часть входных данных может быть отброшена. Если эта ошибка является ErrFinalToken, сканирование останавливается без ошибки. Непустой токен, возвращаемый с ErrFinalToken, будет последним токеном, а пустой токен с ErrFinalToken немедленно остановит сканирование.
В противном случае Scanner продвигает вход. Если токен не пустой, Scanner возвращает его пользователю. Если токен пустой, Scanner считывает больше данных и продолжает сканирование; если больше данных нет (если atEOF был истинным), Scanner возвращается. Если данные ещё не содержат полного токена, например, если при сканировании строк нет новой строки, SplitFunc может вернуть (0, nil, nil), чтобы сигнализировать Scanner о необходимости считывания больше данных в срез и повторной попытке с более длинным срезом, начиная с той же позиции во входных данных.
Функция никогда не вызывается со срезом данных, если он пустой, за исключением случая, когда atEOF равен true. Однако, если atEOF равен true, данные могут быть не пустыми и, как всегда, содержат необработанный текст.
type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error)
type Writer
Writer реализует буферизацию для объекта io.Writer. Если при записи в Writer произошла ошибка, больше данных не будут приниматься, и все последующие записи и Writer.Flush вернут ошибку. После записи всех данных клиент должен вызвать метод Writer.Flush, чтобы гарантировать, что все данные были пересланы в базовый io.Writer.
type Writer struct {
// contains filtered or unexported fields
}
Пример
Код:
w := bufio.NewWriter(os.Stdout) fmt.Fprint(w, "Hello, ") fmt.Fprint(w, "world!") w.Flush() // Don't forget to flush!
Вывод:
Hello, world!
func NewWriter
func NewWriter(w io.Writer) *Writer
NewWriter возвращает новый Writer, буфер которого имеет размер по умолчанию. Если аргумент io.Writer уже является Writer с достаточно большим размером буфера, он возвращает базовый Writer.
func NewWriterSize
func NewWriterSize(w io.Writer, size int) *Writer
NewWriterSize возвращает новый Writer, буфер которого имеет размер как минимум указанного размера. Если аргумент io.Writer уже является Writer с достаточно большим размером, он возвращает базовый Writer.
func (*Writer) Available
func (b *Writer) Available() int
Available возвращает количество байтов, не используемых в буфере.
func (*Writer) AvailableBuffer 1.18
func (b *Writer) AvailableBuffer() []byte
AvailableBuffer возвращает пустой буфер с емкостью b.Available(). Этот буфер предназначен для добавления в него и передачи в последующий вызов Writer.Write. Буфер действителен только до следующей операции записи в b.
Пример
Код:
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()
Вывод:
1 2 3 4
func (*Writer) Buffered
func (b *Writer) Buffered() int
Buffered возвращает количество байтов, записанных в текущий буфер.
func (*Writer) Flush
func (b *Writer) Flush() error
Flush записывает все данные из буфера в базовый io.Writer.
func (*Writer) ReadFrom 1.1
func (b *Writer) ReadFrom(r io.Reader) (n int64, err error)
ReadFrom реализует io.ReaderFrom. Если базовый писатель поддерживает метод ReadFrom, вызывается базовый ReadFrom. Если есть данные в буфере и базовый ReadFrom, буфер заполняется и записывается перед вызовом ReadFrom.
func (*Writer) Reset 1.2
func (b *Writer) Reset(w io.Writer)
Reset отбрасывает все незаписанные данные буфера, очищает любые ошибки и устанавливает b для записи своего вывода в w. Вызов Reset на нулевом значении Writer инициализирует внутренний буфер размером по умолчанию. Вызов w.Reset(w) (т.е. сброс Writer на себя) ничего не делает.
func (*Writer) Size 1.10
func (b *Writer) Size() int
Size возвращает размер базового буфера в байтах.
func (*Writer) Write
func (b *Writer) Write(p []byte) (nn int, err error)
Write записывает содержимое p в буфер. Он возвращает количество записанных байтов. Если nn < len(p), он также возвращает ошибку, объясняющую, почему запись прервана.
func (*Writer) WriteByte
func (b *Writer) WriteByte(c byte) error
WriteByte записывает один байт.
func (*Writer) WriteRune
func (b *Writer) WriteRune(r rune) (size int, err error)
WriteRune записывает один Unicode код, возвращая количество записанных байтов и любые ошибки.
func (*Writer) WriteString
func (b *Writer) WriteString(s string) (int, error)
WriteString записывает строку. Он возвращает количество записанных байтов. Если счёт меньше len(s), он также возвращает ошибку, объясняющую, почему запись прервана.
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/bufio/
