# package bufio `import "bufio"` bufio包實現了有緩沖的I/O。它包裝一個io.Reader或io.Writer接口對象，創建另一個也實現了該接口，且同時還提供了緩沖和一些文本I/O的幫助函數的對象。 ## Index * [Constants](#pkg-constants) * [Variables](#pkg-variables) * [type Reader](#Reader) * [func NewReader(rd io.Reader) \*Reader](#NewReader) * [func NewReaderSize(rd io.Reader, size int) \*Reader](#NewReaderSize) * [func (b \*Reader) Reset(r io.Reader)](#Reader.Reset) * [func (b \*Reader) Buffered() int](#Reader.Buffered) * [func (b \*Reader) Peek(n int) ([]byte, error)](#Reader.Peek) * [func (b \*Reader) Read(p []byte) (n int, err error)](#Reader.Read) * [func (b \*Reader) ReadByte() (c byte, err error)](#Reader.ReadByte) * [func (b \*Reader) UnreadByte() error](#Reader.UnreadByte) * [func (b \*Reader) ReadRune() (r rune, size int, err error)](#Reader.ReadRune) * [func (b \*Reader) UnreadRune() error](#Reader.UnreadRune) * [func (b \*Reader) ReadLine() (line []byte, isPrefix bool, err error)](#Reader.ReadLine) * [func (b \*Reader) ReadSlice(delim byte) (line []byte, err error)](#Reader.ReadSlice) * [func (b \*Reader) ReadBytes(delim byte) (line []byte, err error)](#Reader.ReadBytes) * [func (b \*Reader) ReadString(delim byte) (line string, err error)](#Reader.ReadString) * [func (b \*Reader) WriteTo(w io.Writer) (n int64, err error)](#Reader.WriteTo) * [type Writer](#Writer) * [func NewWriter(w io.Writer) \*Writer](#NewWriter) * [func NewWriterSize(w io.Writer, size int) \*Writer](#NewWriterSize) * [func (b \*Writer) Reset(w io.Writer)](#Writer.Reset) * [func (b \*Writer) Buffered() int](#Writer.Buffered) * [func (b \*Writer) Available() int](#Writer.Available) * [func (b \*Writer) Write(p []byte) (nn int, err error)](#Writer.Write) * [func (b \*Writer) WriteString(s string) (int, error)](#Writer.WriteString) * [func (b \*Writer) WriteByte(c byte) error](#Writer.WriteByte) * [func (b \*Writer) WriteRune(r rune) (size int, err error)](#Writer.WriteRune) * [func (b \*Writer) Flush() error](#Writer.Flush) * [func (b \*Writer) ReadFrom(r io.Reader) (n int64, err error)](#Writer.ReadFrom) * [type ReadWriter](#ReadWriter) * [func NewReadWriter(r \*Reader, w \*Writer) \*ReadWriter](#NewReadWriter) * [type SplitFunc](#SplitFunc) * [func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error)](#ScanBytes) * [func ScanRunes(data []byte, atEOF bool) (advance int, token []byte, err error)](#ScanRunes) * [func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error)](#ScanWords) * [func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error)](#ScanLines) * [type Scanner](#Scanner) * [func NewScanner(r io.Reader) \*Scanner](#NewScanner) * [func (s \*Scanner) Split(split SplitFunc)](#Scanner.Split) * [func (s \*Scanner) Scan() bool](#Scanner.Scan) * [func (s \*Scanner) Bytes() []byte](#Scanner.Bytes) * [func (s \*Scanner) Text() string](#Scanner.Text) * [func (s \*Scanner) Err() error](#Scanner.Err) ### Examples * [Scanner (Custom)](#example-Scanner--Custom) * [Scanner (Lines)](#example-Scanner--Lines) * [Scanner (Words)](#example-Scanner--Words) * [Writer](#example-Writer) ## Constants ``` const ( // 用于緩沖一個token，實際需要的最大token尺寸可能小一些，例如緩沖中需要保存一整行內容 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") ) ``` 會被Scanner類型返回的錯誤。 ## type [Reader](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L31 "View Source") ``` type Reader struct { // 內含隱藏或非導出字段 } ``` Reader實現了給一個io.Reader接口對象附加緩沖。 ### func [NewReader](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L61 "View Source") ``` func NewReader(rd io.Reader) *Reader ``` NewReader創建一個具有默認大小緩沖、從r讀取的\*Reader。 ### func [NewReaderSize](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L46 "View Source") ``` func NewReaderSize(rd io.Reader, size int) *Reader ``` NewReaderSize創建一個具有最少有size尺寸的緩沖、從r讀取的\*Reader。如果參數r已經是一個具有足夠大緩沖的* Reader類型值，會返回r。 ### func (\*Reader) [Reset](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L67 "View Source") ``` func (b *Reader) Reset(r io.Reader) ``` Reset丟棄緩沖中的數據，清除任何錯誤，將b重設為其下層從r讀取數據。 ### func (\*Reader) [Buffered](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L261 "View Source") ``` func (b *Reader) Buffered() int ``` Buffered返回緩沖中現有的可讀取的字節數。 ### func (\*Reader) [Peek](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L123 "View Source") ``` func (b *Reader) Peek(n int) ([]byte, error) ``` Peek返回輸入流的下n個字節，而不會移動讀取位置。返回的[]byte只在下一次調用讀取操作前合法。如果Peek返回的切片長度比n小，它也會返會一個錯誤說明原因。如果n比緩沖尺寸還大，返回的錯誤將是ErrBufferFull。 ### func (\*Reader) [Read](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L153 "View Source") ``` func (b *Reader) Read(p []byte) (n int, err error) ``` Read讀取數據寫入p。本方法返回寫入p的字節數。本方法一次調用最多會調用下層Reader接口一次Read方法，因此返回值n可能小于len(p)。讀取到達結尾時，返回值n將為0而err將為io.EOF。 ### func (\*Reader) [ReadByte](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L193 "View Source") ``` func (b *Reader) ReadByte() (c byte, err error) ``` ReadByte讀取并返回一個字節。如果沒有可用的數據，會返回錯誤。 ### func (\*Reader) [UnreadByte](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L208 "View Source") ``` func (b *Reader) UnreadByte() error ``` UnreadByte吐出最近一次讀取操作讀取的最后一個字節。（只能吐出最后一個，多次調用會出問題） ### func (\*Reader) [ReadRune](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L228 "View Source") ``` func (b *Reader) ReadRune() (r rune, size int, err error) ``` ReadRune讀取一個utf-8編碼的unicode碼值，返回該碼值、其編碼長度和可能的錯誤。如果utf-8編碼非法，讀取位置只移動1字節，返回U+FFFD，返回值size為1而err為nil。如果沒有可用的數據，會返回錯誤。 ### func (\*Reader) [UnreadRune](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L250 "View Source") ``` func (b *Reader) UnreadRune() error ``` UnreadRune吐出最近一次ReadRune調用讀取的unicode碼值。如果最近一次讀取不是調用的ReadRune，會返回錯誤。（從這點看，UnreadRune比UnreadByte嚴格很多） ### func (\*Reader) [ReadLine](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L325 "View Source") ``` func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error) ``` ReadLine是一個低水平的行數據讀取原語。大多數調用者應使用ReadBytes('\n')或ReadString('\n')代替，或者使用Scanner。 ReadLine嘗試返回一行數據，不包括行尾標志的字節。如果行太長超過了緩沖，返回值isPrefix會被設為true，并返回行的前面一部分。該行剩下的部分將在之后的調用中返回。返回值isPrefix會在返回該行最后一個片段時才設為false。返回切片是緩沖的子切片，只在下一次讀取操作之前有效。ReadLine要么返回一個非nil的line，要么返回一個非nil的err，兩個返回值至少一個非nil。 返回的文本不包含行尾的標志字節（"\r\n"或"\n"）。如果輸入流結束時沒有行尾標志字節，方法不會出錯，也不會指出這一情況。在調用ReadLine之后調用UnreadByte會總是吐出最后一個讀取的字節（很可能是該行的行尾標志字節），即使該字節不是ReadLine返回值的一部分。 ### func (\*Reader) [ReadSlice](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L273 "View Source") ``` func (b *Reader) ReadSlice(delim byte) (line []byte, err error) ``` ReadSlice讀取直到第一次遇到delim字節，返回緩沖里的包含已讀取的數據和delim字節的切片。該返回值只在下一次讀取操作之前合法。如果ReadSlice放在在讀取到delim之前遇到了錯誤，它會返回在錯誤之前讀取的數據在緩沖中的切片以及該錯誤（一般是io.EOF）。如果在讀取到delim之前緩沖就被寫滿了，ReadSlice失敗并返回ErrBufferFull。因為ReadSlice的返回值會被下一次I/O操作重寫，調用者應盡量使用ReadBytes或ReadString替代本法功法。當且僅當ReadBytes方法返回的切片不以delim結尾時，會返回一個非nil的錯誤。 ### func (\*Reader) [ReadBytes](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L367 "View Source") ``` func (b *Reader) ReadBytes(delim byte) (line []byte, err error) ``` ReadBytes讀取直到第一次遇到delim字節，返回一個包含已讀取的數據和delim字節的切片。如果ReadBytes方法在讀取到delim之前遇到了錯誤，它會返回在錯誤之前讀取的數據以及該錯誤（一般是io.EOF）。當且僅當ReadBytes方法返回的切片不以delim結尾時，會返回一個非nil的錯誤。 ### func (\*Reader) [ReadString](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L415 "View Source") ``` func (b *Reader) ReadString(delim byte) (line string, err error) ``` ReadString讀取直到第一次遇到delim字節，返回一個包含已讀取的數據和delim字節的字符串。如果ReadString方法在讀取到delim之前遇到了錯誤，它會返回在錯誤之前讀取的數據以及該錯誤（一般是io.EOF）。當且僅當ReadString方法返回的切片不以delim結尾時，會返回一個非nil的錯誤。 ### func (\*Reader) [WriteTo](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L422 "View Source") ``` func (b *Reader) WriteTo(w io.Writer) (n int64, err error) ``` WriteTo方法實現了io.WriterTo接口。 ## type [Writer](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L479 "View Source") ``` type Writer struct { // 內含隱藏或非導出字段 } ``` Writer實現了為io.Writer接口對象提供緩沖。如果在向一個Writer類型值寫入時遇到了錯誤，該對象將不再接受任何數據，且所有寫操作都會返回該錯誤。在說有數據都寫入后，調用者有義務調用Flush方法以保證所有的數據都交給了下層的io.Writer。 Example ``` w := bufio.NewWriter(os.Stdout) fmt.Fprint(w, "Hello, ") fmt.Fprint(w, "world!") w.Flush() // Don't forget to flush! ``` Output: ``` Hello, world! ``` ### func [NewWriter](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L505 "View Source") ``` func NewWriter(w io.Writer) *Writer ``` NewWriter創建一個具有默認大小緩沖、寫入w的\*Writer。 ### func [NewWriterSize](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L489 "View Source") ``` func NewWriterSize(w io.Writer, size int) *Writer ``` NewWriterSize創建一個具有最少有size尺寸的緩沖、寫入w的\*Writer。如果參數w已經是一個具有足夠大緩沖的\*Writer類型值，會返回w。 ### func (\*Writer) [Reset](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L511 "View Source") ``` func (b *Writer) Reset(w io.Writer) ``` Reset丟棄緩沖中的數據，清除任何錯誤，將b重設為將其輸出寫入w。 ### func (\*Writer) [Buffered](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L550 "View Source") ``` func (b *Writer) Buffered() int ``` Buffered返回緩沖中已使用的字節數。 ### func (\*Writer) [Available](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L547 "View Source") ``` func (b *Writer) Available() int ``` Available返回緩沖中還有多少字節未使用。 ### func (\*Writer) [Write](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L556 "View Source") ``` func (b *Writer) Write(p []byte) (nn int, err error) ``` Write將p的內容寫入緩沖。返回寫入的字節數。如果返回值nn < len(p)，還會返回一個錯誤說明原因。 ### func (\*Writer) [WriteString](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L626 "View Source") ``` func (b *Writer) WriteString(s string) (int, error) ``` WriteString寫入一個字符串。返回寫入的字節數。如果返回值nn < len(s)，還會返回一個錯誤說明原因。 ### func (\*Writer) [WriteByte](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L581 "View Source") ``` func (b *Writer) WriteByte(c byte) error ``` WriteByte寫入單個字節。 ### func (\*Writer) [WriteRune](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L595 "View Source") ``` func (b *Writer) WriteRune(r rune) (size int, err error) ``` WriteRune寫入一個unicode碼值（的utf-8編碼），返回寫入的字節數和可能的錯誤。 ### func (\*Writer) [Flush](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L518 "View Source") ``` func (b *Writer) Flush() error ``` Flush方法將緩沖中的數據寫入下層的io.Writer接口。 ### func (\*Writer) [ReadFrom](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L645 "View Source") ``` func (b *Writer) ReadFrom(r io.Reader) (n int64, err error) ``` ReadFrom實現了io.ReaderFrom接口。 ## type [ReadWriter](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L690 "View Source") ``` type ReadWriter struct { *Reader *Writer } ``` ReadWriter類型保管了指向Reader和Writer類型的指針，（因此）實現了io.ReadWriter接口。 ### func [NewReadWriter](https://github.com/golang/go/blob/master/src/bufio/bufio.go#L696 "View Source") ``` func NewReadWriter(r *Reader, w *Writer) *ReadWriter ``` NewReadWriter申請創建一個新的、將讀寫操作分派給r和w?的ReadWriter。 ## type [SplitFunc](https://github.com/golang/go/blob/master/src/bufio/scan.go#L57 "View Source") ``` type SplitFunc func(data []byte, atEOF bool) (advance int, token []byte, err error) ``` SplitFunc類型代表用于對輸出作詞法分析的分割函數。 參數data是尚未處理的數據的一個開始部分的切片，參數atEOF表示是否Reader接口不能提供更多的數據。返回值是解析位置前進的字節數，將要返回給調用者的token切片，以及可能遇到的錯誤。如果數據不足以（保證）生成一個完整的token，例如需要一整行數據但data里沒有換行符，SplitFunc可以返回(0, nil, nil)來告訴Scanner讀取更多的數據寫入切片然后用從同一位置起始、長度更長的切片再試一次（調用SplitFunc類型函數）。 如果返回值err非nil，掃描將終止并將該錯誤返回給Scanner的調用者。 除非atEOF為真，永遠不會使用空切片data調用SplitFunc類型函數。然而，如果atEOF為真，data卻可能是非空的、且包含著未處理的文本。 ## func [ScanBytes](https://github.com/golang/go/blob/master/src/bufio/scan.go#L213 "View Source") ``` func ScanBytes(data []byte, atEOF bool) (advance int, token []byte, err error) ``` ScanBytes是用于Scanner類型的分割函數（符合SplitFunc），本函數會將每個字節作為一個token返回。 ## func [ScanRunes](https://github.com/golang/go/blob/master/src/bufio/scan.go#L228 "View Source") ``` func ScanRunes(data []byte, atEOF bool) (advance int, token []byte, err error) ``` ScanRunes是用于Scanner類型的分割函數（符合SplitFunc），本函數會將每個utf-8編碼的unicode碼值作為一個token返回。本函數返回的rune序列和range一個字符串的輸出rune序列相同。錯誤的utf-8編碼會翻譯為U+FFFD = "\xef\xbf\xbd"，但只會消耗一個字節。調用者無法區分正確編碼的rune和錯誤編碼的rune。 ## func [ScanWords](https://github.com/golang/go/blob/master/src/bufio/scan.go#L319 "View Source") ``` func ScanWords(data []byte, atEOF bool) (advance int, token []byte, err error) ``` ScanRunes是用于Scanner類型的分割函數（符合SplitFunc），本函數會將空白（參見unicode.IsSpace）分隔的片段（去掉前后空白后）作為一個token返回。本函數永遠不會返回空字符串。 ## func [ScanLines](https://github.com/golang/go/blob/master/src/bufio/scan.go#L274 "View Source") ``` func ScanLines(data []byte, atEOF bool) (advance int, token []byte, err error) ``` ScanRunes是用于Scanner類型的分割函數（符合SplitFunc），本函數會將每一行文本去掉末尾的換行標記作為一個token返回。返回的行可以是空字符串。換行標記為一個可選的回車后跟一個必選的換行符。最后一行即使沒有換行符也會作為一個token返回。 ## type [Scanner](https://github.com/golang/go/blob/master/src/bufio/scan.go#L30 "View Source") ``` type Scanner struct { // 內含隱藏或非導出字段 } ``` Scanner類型提供了方便的讀取數據的接口，如從換行符分隔的文本里讀取每一行。 成功調用的Scan方法會逐步提供文件的token，跳過token之間的字節。token由SplitFunc類型的分割函數指定；默認的分割函數會將輸入分割為多個行，并去掉行尾的換行標志。本包預定義的分割函數可以將文件分割為行、字節、unicode碼值、空白分隔的word。調用者可以定制自己的分割函數。 掃描會在抵達輸入流結尾、遇到的第一個I/O錯誤、token過大不能保存進緩沖時，不可恢復的停止。當掃描停止后，當前讀取位置可能會遠在最后一個獲得的token后面。需要更多對錯誤管理的控制或token很大，或必須從reader連續掃描的程序，應使用bufio.Reader代替。 Example (Custom) ``` // 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) } ``` Output: ``` 1234 5678 Invalid input: strconv.ParseInt: parsing "1234567901234567890": value out of range ``` Example (Lines) ``` 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) ``` // 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) ``` Output: ``` 15 ``` ### func [NewScanner](https://github.com/golang/go/blob/master/src/bufio/scan.go#L74 "View Source") ``` func NewScanner(r io.Reader) *Scanner ``` NewScanner創建并返回一個從r讀取數據的Scanner，默認的分割函數是ScanLines。 ### func (\*Scanner) [Split](https://github.com/golang/go/blob/master/src/bufio/scan.go#L206 "View Source") ``` func (s *Scanner) Split(split SplitFunc) ``` Split設置該Scanner的分割函數。本方法必須在Scan之前調用。 ### func (\*Scanner) [Scan](https://github.com/golang/go/blob/master/src/bufio/scan.go#L110 "View Source") ``` func (s *Scanner) Scan() bool ``` Scan方法獲取當前位置的token（該token可以通過Bytes或Text方法獲得），并讓Scanner的掃描位置移動到下一個token。當掃描因為抵達輸入流結尾或者遇到錯誤而停止時，本方法會返回false。在Scan方法返回false后，Err方法將返回掃描時遇到的任何錯誤；除非是io.EOF，此時Err會返回nil。 ### func (\*Scanner) [Bytes](https://github.com/golang/go/blob/master/src/bufio/scan.go#L94 "View Source") ``` func (s *Scanner) Bytes() []byte ``` Bytes方法返回最近一次Scan調用生成的token。底層數組指向的數據可能會被下一次Scan的調用重寫。 ### func (\*Scanner) [Text](https://github.com/golang/go/blob/master/src/bufio/scan.go#L100 "View Source") ``` func (s *Scanner) Text() string ``` Bytes方法返回最近一次Scan調用生成的token，會申請創建一個字符串保存token并返回該字符串。 ### func (\*Scanner) [Err](https://github.com/golang/go/blob/master/src/bufio/scan.go#L84 "View Source") ``` func (s *Scanner) Err() error ``` Err返回Scanner遇到的第一個非EOF的錯誤。