bufio: add examples for Scanner

Mention Scanner in docs for ReadLine etc.

R=golang-dev, bradfitz
CC=golang-dev
https://golang.org/cl/7375045

diff --git a/src/pkg/bufio/bufio.go b/src/pkg/bufio/bufio.go
index 33779014c9c90b855c95459d86ac28026e2cd0b1..ee69c2d31e4f55bab7b7498f3d370b3c85041ac9 100644 (file)
--- a/src/pkg/bufio/bufio.go
+++ b/src/pkg/bufio/bufio.go
@@ -278,7 +278,7 @@ func (b *Reader) ReadSlice(delim byte) (line []byte, err error) {
 }
 
 // ReadLine is a low-level line-reading primitive. Most callers should use
-// ReadBytes('\n') or ReadString('\n') instead.
+// 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
@@ -331,6 +331,7 @@ func (b *Reader) ReadLine() (line []byte, isPrefix bool, err error) {
 // 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 (b *Reader) ReadBytes(delim byte) (line []byte, err error) {
        // Use ReadSlice to look for array,
        // accumulating full buffers.
@@ -378,6 +379,7 @@ func (b *Reader) ReadBytes(delim byte) (line []byte, err error) {
 // 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 (b *Reader) ReadString(delim byte) (line string, err error) {
        bytes, err := b.ReadBytes(delim)
        return string(bytes), err

diff --git a/src/pkg/bufio/example_test.go b/src/pkg/bufio/example_test.go
new file mode 100644 (file)
index 0000000..b545ce3
--- /dev/null
+++ b/src/pkg/bufio/example_test.go
@@ -0,0 +1,74 @@
+// Copyright 2013 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package bufio_test
+
+import (
+       "bufio"
+       "fmt"
+       "os"
+       "strconv"
+       "strings"
+)
+
+// The simplest use of a Scanner, to read standard input as a set of lines.
+func ExampleScanner_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.Stdout, "reading standard input:", err)
+       }
+}
+
+// Use a Scanner to implement a simple word-count utility by scanning the
+// input as a sequence of space-delimited tokens.
+func ExampleScanner_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.Stdout, "reading input:", err)
+       }
+       fmt.Printf("%d\n", count)
+       // Output: 15
+}
+
+// Use a Scanner with a custom split function (built by wrapping ScanWords) to validate
+// 32-bit decimal input.
+func ExampleScanner_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
+}