...

パッケージ bufio

import "bufio"
概要
目次

概要 ▾

bufio パッケージは,バッファ付き I/O を実装します。 io.Reader や io.Writer オブジェクトをラップし, バッファ機能やその他のテキスト I/O で役に立つ機能を追加した別のオブジェクト (Reader あるいは Writer) を作成します。

目次 ▾

定数
変数
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
    func NewReadWriter(r *Reader, w *Writer) *ReadWriter
type Reader
    func NewReader(rd io.Reader) *Reader
    func NewReaderSize(rd io.Reader, size int) *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
    func NewScanner(r io.Reader) *Scanner
    func (s *Scanner) Buffer(buf []byte, max int)
    func (s *Scanner) Bytes() []byte
    func (s *Scanner) Err() error
    func (s *Scanner) Scan() bool
    func (s *Scanner) Split(split SplitFunc)
    func (s *Scanner) Text() string
type SplitFunc
type Writer
    func NewWriter(w io.Writer) *Writer
    func NewWriterSize(w io.Writer, size int) *Writer
    func (b *Writer) Available() int
    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)

パッケージファイル

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")
)

ErrFinalToken は,特別なエラー値です。 分割関数がこのエラーを返すのは,このトークンが最後で, 以降のスキャンを中止すべきことを伝えます。 Scan で ErrFinalToken を受け取ったなら,エラーなしでスキャンを中止します。 この値は,処理を早めに終えたり,最後の空トークンを返す必要がある場合に役立ちます。 自分で作成したエラー値を使って同様の振る舞いをさせることもできますが, ここで用意したエラー値を使う方が見通しが良くなります。 この値の使い方の例として,emptyFinalToken の例をご覧ください。

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

func ScanBytes 1.1

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

ScanBytes は,各バイトをトークンとして返す分割関数です。

func ScanLines 1.1

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

ScanLines は,テキストの各行を返す分割関数です。 ただし,改行マーカーはトークンに含まれません。 空文字の場合もあります。改行マーカーとは,1 つあるいは 0 個のキャリッジリターンとそれに続く 1 つのニューラインです。 正規表現では, `\r?\n` となります。 入力の最後の空でない行は,改行マーカーがなかったとしても返ります。

func ScanRunes 1.1

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

ScanRunes は,UTF-8 でエンコードされた rune をトークンとして返す分割関数です。 返される rune のシーケンスは 入力を文字列として range ループした時と同じになります。 つまり,誤った UTF-8 エンコードは U+FFFD = "\xef\xbf\xbd" となります。 Scan インターフェースの都合上, エンコードエラーと正しく U+FFFD であった場合を区別することはできません。

func ScanWords 1.1

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

ScanWords は,空白で区切られた単語を返す分割関数です。 トークンに空白は含まれません。 空文字列を返すことはありません。 空白は unicode.IsSpace で定義されます。

type ReadWriter

ReadWriter は, Reader と Writer へのポインタを保持します。 io.ReadWriter を実装します。

type ReadWriter struct {
    *Reader
    *Writer
}

func NewReadWriter

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

NewReadWriter は,r と w に操作を割り振る新しい ReadWriter を返します。

type Reader

Reader は,io.Reader オブジェクトにバッファ機能を実装します。

type Reader struct {
    // エクスポートされていないフィールドがあります
}

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 で,すでに十分大きなサイズのバッファを持つならば, それ自身を返します。

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 バイトを reader を進めることなく返します。The bytes stop Peek が n バイトより少ないデータを返した場合, なぜ少ないのか説明したエラーも返します。 n が b のバッファサイズより大きい場合, ErrBufferFull を返します。

Peek を呼び出したなら,次の read 操作を行うまで, UnreadByte や UnreadRune を続けて呼ぶことはできません。

func (*Reader) Read

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

Read はデータを p に読み込みます。 p に読み込まれたバイト数を返します。 内部の Reader の Read を最大 1 回呼び出し,バイトを読み込みます。 そのため, n は len(p) より少ない場合があります。 len(p) バイトきっかり読み込むためには,io.ReadFull(b, p) を使います。 EOF では,バイト数は 0 で,err は io.EOF となります。

func (*Reader) ReadByte

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

ReadByte は 1 バイト読み込み,返します。 1 バイトも読み込めない場合,エラーを返します。

func (*Reader) ReadBytes

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

ReadBytes は,delim が出現するまで読み込み, delim を含めた,delim までのスライスを返します。 delim を見つける前にエラーが生じた場合, そのエラー前までに読み込まれたデータと,エラー (多くの場合,io.EOF) を返します。 ReadBytes は返り値が delim で終わっていない時に,またその時だけ, err != nil となります。

シンプルなユースケースの場合,Scanner のほうが便利です。

func (*Reader) ReadLine

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

ReadLine は,原始的な行読み込み関数です。 大抵の場合,ReadBytes('\n') や ReadString('\n') を使うか,Scanner を使うべきです。

ReadLine は,行末を示すバイトを除いた 1 行を返します。 行がバッファより長い場合,isPrefix が true となり,行の最初の部分が返されます。 行の残りの部分は次回の呼び出しで返ります。 行の残りの部分を返す時には,isPrefix は false となります。 返り値のバッファはもう一度 ReadLine を呼ぶ前まで使うことができます。 ReadLine は nil でない line を返すか,エラーを返します。 どちらも返すことはありません。

ReadLine で返る値には行末 ("\r\n" あるいは "\n") は含まれていません。 入力の最後が行末でなくても,エラーは返りません。 ReadLine を呼び出した後に UnreadByte を呼び出す場合,読み込まれた最後のバイト(行末文字かもしれない)を未読み込み状態に戻します。 たとえそのバイトが ReadLine で返る line の一部分でなかったとしてもです。

func (*Reader) ReadRune

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

ReadRune は 1 つの UTF-8 でエンコードされた Unicode 文字を読み込み, その rune とバイト数を返します。rune が正しくない場合,1 バイト読み込み, unicode.ReplacementChar (U+FFFD) とバイト数 1 を返します。

func (*Reader) ReadSlice

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

ReadSlice は,delim が出現するまで読み込み, バッファのバイト列を指すスライスを返します。

delim を見つける前にエラーが生じた場合, バッファのすべてのデータとそのエラーを返します。(大抵の場合,io.EOF) バッファが delim を見つける前にいっぱいになると,ReadSlice はエラー ErrBufferFull を返します。 ReadSlice で返されるデータは 以降の I/O 操作で変更される可能性があるため, 大抵の場合,かわりに ReadBytes や ReadString を使うのが良いでしょう。 ReadSlice は,line が delim で終わらない場合に必ず,またそのときのみ, err != nil となります。

func (*Reader) ReadString

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

ReadString は,delim が現れるまで読み込み, delim を含めた,delim までの文字列を返します。 delim を見つける前にエラーが生じた場合, そのエラー前までに読み込まれたデータと,エラー (多くの場合,io.EOF) を返します。 ReadString は返り値が delim で終わっていない時に,またその時だけ, err != nil となります。

シンプルなユースケースの場合,Scanner のほうが便利です。

func (*Reader) Reset 1.2

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

Reset は,バッファされたデータを全て捨て,すべての状態をリセットし, r から読み込むように変更します。

func (*Reader) Size 1.10

func (b *Reader) Size() int

Size は,内部のバッファのバイト数を返します。

func (*Reader) UnreadByte

func (b *Reader) UnreadByte() error

UnreadByte は,最後のバイトを読み込んでいない状態に戻します。最後に読んだバイトにのみ適用できます。

最後に呼ばれたメソッドが読み込み操作でなかった場合, UnreadByte はエラーを返します。 注意すべき点として,Peek は読み込み操作ではありません。

func (*Reader) UnreadRune

func (b *Reader) UnreadRune() error

UnreadRune は最後の rune を読み込んでいない状態に戻します。この Reader の最後の呼び出しが ReadRune でない場合, UnreadRune はエラーを返します。 (この条件は,UnreadByte よりも厳しいと言えます。 UnreadByte は最後の呼び出しがどの読み込み操作であっても,最後のバイトを読み込んでいない状態に戻すことが可能だからです。)

func (*Reader) WriteTo 1.1

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

WriteTo は io.WriterTo を実装します。 内部の Reader の Read メソッドを複数回呼ぶことがあります。 もし内部の Reader が WriteTo メソッドを持っているならば, バッファせずにその WriteTo メソッドを呼びます。

type Scanner 1.1

Scanner は,改行で区切られたテキストファイル等のデータを読み込むのに便利です。 Scan メソッドを呼び出すと, ファイルのトークンを読み込み, トークン間のバイトをスキップします。 トークンは SplitFunc 型の分割関数で定義します。the default split デフォルトの分割関数は,改行コードを取り除いた形で入力を各行に分割します。 このパッケージで定義された分割関数には, ファイルを行ごと,バイトごと,UTF-8 でエンコードされた rune ごと,空白で区切られた単語ごと読み込むための関数があります。 独自の分割関数を用意することも可能です。

EOF,最初の I/O エラー,あるいはトークンが大きすぎてバッファに治らない場合,スキャンはストップし,回復させることはできません。 スキャンがストップすると,reader は最後のトークンよりあとのどの部分にも進んでいる可能性があります。 さらに緻密なエラーハンドリングが必要な場合や大きなトークンを読み込む必要がある場合,あるいは reader に対してシーケンシャルにスキャンする必要がある場合, bufio.Reader をかわりに用いるべきです。

type Scanner struct {
    // エクスポートされていないフィールドがあります
}

例 (Custom)

ScanWords をラップした独自の分割関数を使った Scanner を使い, 32ビット小数入力が正しいかを判定する。

コード:

// 人工的な入力
const input = "1234 5678 1234567901234567890"
scanner := bufio.NewScanner(strings.NewReader(input))
// ScanWords 関数をラップして,独自の分割関数を作る。
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
}
// スキャン操作用の分割関数を設定する。
scanner.Split(split)
// 入力が正しいかチェックする
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

例 (EmptyFinalToken)

独自の分割関数を持つ Scanner を使って,カンマで区切られたリストを パースする。

コード:

// カンマで区切られたリスト。最後は空文字。
const input = "1,2,3,4,"
scanner := bufio.NewScanner(strings.NewReader(input))
// カンマで区切る分割関数を定義する。
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
    }
    // 最後のトークン。空文字かもしれない。
    // bufio.ErrFinalToken を返すことによって,これ以上トークンが存在しないことを示す。
    // しかし,Scan 自身からエラーを返すことにはならない。
    return 0, data, bufio.ErrFinalToken
}
scanner.Split(onComma)
// スキャンする。
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" ""

例 (Lines)

もっともシンプルな Scanner の使い方。標準入力から,毎行読み込みます。

コード:

scanner := bufio.NewScanner(os.Stdin)
for scanner.Scan() {
    fmt.Println(scanner.Text()) // Println で行末の '\n' を元に戻す
}
if err := scanner.Err(); err != nil {
    fmt.Fprintln(os.Stderr, "reading standard input:", err)
}

例 (Words)

Scanner を使って,空白で区切られた単語数を数えます。

コード:

// 人工的な入力
const input = "Now is the winter of our discontent,\nMade glorious summer by this sun of York.\n"
scanner := bufio.NewScanner(strings.NewReader(input))
// スキャン操作用の分割関数を設定する。
scanner.Split(bufio.ScanWords)
// 単語を数える。
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 は, r から読み込む新しい Scanner を返します。 分割関数は,デフォルトで ScanLines になります。

func (*Scanner) Buffer 1.6

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

Buffer は,スキャンで最初に用いるバッファと スキャン中に割り当て可能な最大のバッファサイズを設定します。 最大のトークンサイズは max と cap(buf) の大きい方となります。 max <= cap(buf) の場合, Scan はこのバッファだけ使い,他の割り当ては行いません。

デフォルトで, Scan は内部のバッファを用い, 最大トークンサイズは MaxScanTokenSize です。

スキャンを開始した後に Buffer を呼び出すとパニックします。

func (*Scanner) Bytes 1.1

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

Bytes は,Scan 呼び出しで最後に生成されたトークンを返します。 内部の配列は,次回の Scan 呼び出しで上書きされるかもしれないデータを指しており, メモリ割り当ては行なっていないことに注意してください。

Return the most recent call to Scan as a []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 は,Scanner で生じた最初の EOF 以外のエラーを返します。

func (*Scanner) Scan 1.1

func (s *Scanner) Scan() bool

Scan は Scanner で次のトークンまで処理し, そのトークンは Bytes あるいは Text メソッドで取得可能になります。 スキャンが終わった時には false を返します。スキャンが終わるのは,入力の最後までスキャンされた場合か,エラーが発生した場合です。 Scan が false を返してから,Err メソッドを使ってスキャン中に発生したエラーを取得できます。 ただし,そのエラーが io.EOF だった場合は, Err は nil を返します。 入力を進めることなく多くの空のトークンを返した場合,Scan はパニックします。 これは,Scanner で共通のエラー通知方法です。

func (*Scanner) Split 1.1

func (s *Scanner) Split(split SplitFunc)

Split は,Scanner が用いる分割関数を設定します。 デフォルトの分割関数は ScanLines です。

スキャン開始後に Split を呼び出すとパニックします。

func (*Scanner) Text 1.1

func (s *Scanner) Text() string

Text は,Scan 呼び出しで最後に生成されたトークンを返します。 このトークンのバイトを持つ,新たにメモリを割り当てられた文字列を返します。

type SplitFunc 1.1

SplitFunc は,入力をトークンに分けるための分割関数の型です。 引数は,まだ処理されていない残りの部分文字列と, Reader にはもうデータがないことを表すフラグ atEOF です。 返り値は,入力を処理したバイト数, トークン(もしあれば),そしてエラー(もしあれば)です。

関数がエラーを返したならスキャンはストップします。 この場合,入力のある部分が捨てられるかもしれません。

それ以外の場合, Scanner は入力を処理していきます。トークンが nil でなければ, Scanner はそれを返します。トークンが nil なら, Scanner はさらにデータを読み込み,スキャンを続けます。 データがなくなれば(atEOF が true ならば) 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 オブジェクトにバッファ機能を実装します。 書き込む際にエラーが生じた場合, データを受け付けなくなり,すべての書き込みと Flush はエラーを返します。 データを書き終えた後は,Flush メソッドを呼んで すべてのデータが内部の io.Writer に転送されていることを保証すべきです。

type Writer struct {
    // エクスポートされていないフィールドがあります
}

コード:

w := bufio.NewWriter(os.Stdout)
fmt.Fprint(w, "Hello, ")
fmt.Fprint(w, "world!")
w.Flush() // Flush を呼び出すのを忘れないように!

出力:

Hello, world!

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriter は,デフォルトサイズのバッファを持つ新しい 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) 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 を実装します。 内部の writer が ReadFrom メソッドを持っていて, b にまだデータがバッファされていない場合, バッファせずに内部の ReadFrom を呼び出します。

func (*Writer) Reset 1.2

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

Reset は,バッファされたデータを全て捨て,エラーを消し, b の出力を w に書き込むように変更します。

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 は,1 バイト書き込みます。

func (*Writer) WriteRune

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

WriteRune は,1 つの Unicode コードポイントを書き込みます。 書き込まれたバイト数とエラー(もしあれば)を返します。

func (*Writer) WriteString

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

WriteString は文字列を書き込みます。 書き込まれたバイト数を返します。 バイト数が len(s) よりも少ない場合, なぜ書き込みが少ないかを説明するエラーも返します。