io: add examples to functions

Change-Id: Id72cf4daceb7669cf9c7247df8e3ba086ccfe96e
Reviewed-on: https://go-review.googlesource.com/12730
Reviewed-by: Russ Cox <rsc@golang.org>

diff --git a/src/io/example_test.go b/src/io/example_test.go
new file mode 100644 (file)
index 0000000..412dfb3
--- /dev/null
+++ b/src/io/example_test.go
@@ -0,0 +1,223 @@
+// Copyright 2015 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 io_test
+
+import (
+       "bytes"
+       "fmt"
+       "io"
+       "io/ioutil"
+       "log"
+       "os"
+       "strings"
+)
+
+func ExampleCopy() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+
+       if _, err := io.Copy(os.Stdout, r); err != nil {
+               log.Fatal(err)
+       }
+
+       // Output:
+       // some io.Reader stream to be read
+}
+
+func ExampleCopyBuffer() {
+       r1 := strings.NewReader("first reader\n")
+       r2 := strings.NewReader("second reader\n")
+       buf := make([]byte, 8)
+
+       // buf is used here...
+       if _, err := io.CopyBuffer(os.Stdout, r1, buf); err != nil {
+               log.Fatal(err)
+       }
+
+       // ... reused here also. No need to allocate an extra buffer.
+       if _, err := io.CopyBuffer(os.Stdout, r2, buf); err != nil {
+               log.Fatal(err)
+       }
+
+       // Output:
+       // first reader
+       // second reader
+}
+
+func ExampleCopyN() {
+       r := strings.NewReader("some io.Reader stream to be read")
+
+       if _, err := io.CopyN(os.Stdout, r, 5); err != nil {
+               log.Fatal(err)
+       }
+
+       // Output:
+       // some
+}
+
+func ExampleReadAtLeast() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+
+       buf := make([]byte, 33)
+       if _, err := io.ReadAtLeast(r, buf, 4); err != nil {
+               log.Fatal(err)
+       }
+       fmt.Printf("%s\n", buf)
+
+       // buffer smaller than minimal read size.
+       shortBuf := make([]byte, 3)
+       if _, err := io.ReadAtLeast(r, shortBuf, 4); err != nil {
+               fmt.Println("error:", err)
+       }
+
+       // minimal read size bigger than io.Reader stream
+       longBuf := make([]byte, 64)
+       if _, err := io.ReadAtLeast(r, longBuf, 64); err != nil {
+               fmt.Println("error:", err)
+       }
+
+       // Output:
+       // some io.Reader stream to be read
+       //
+       // error: short buffer
+       // error: EOF
+}
+
+func ExampleReadFull() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+
+       buf := make([]byte, 4)
+       if _, err := io.ReadFull(r, buf); err != nil {
+               log.Fatal(err)
+       }
+       fmt.Printf("%s\n", buf)
+
+       // minimal read size bigger than io.Reader stream
+       longBuf := make([]byte, 64)
+       if _, err := io.ReadFull(r, longBuf); err != nil {
+               fmt.Println("error:", err)
+       }
+
+       // Output:
+       // some
+       // error: unexpected EOF
+}
+
+func ExampleWriteString() {
+       io.WriteString(os.Stdout, "Hello World")
+
+       // Output: Hello World
+}
+
+func ExampleLimitReader() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+       lr := io.LimitReader(r, 4)
+
+       if _, err := io.Copy(os.Stdout, lr); err != nil {
+               log.Fatal(err)
+       }
+
+       // Output:
+       // some
+}
+
+func ExampleMultiReader() {
+       r1 := strings.NewReader("first reader ")
+       r2 := strings.NewReader("second reader ")
+       r3 := strings.NewReader("third reader\n")
+       r := io.MultiReader(r1, r2, r3)
+
+       if _, err := io.Copy(os.Stdout, r); err != nil {
+               log.Fatal(err)
+       }
+
+       // Output:
+       // first reader second reader third reader
+}
+
+func ExampleTeeReader() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+       var buf bytes.Buffer
+       tee := io.TeeReader(r, &buf)
+
+       printall := func(r io.Reader) {
+               b, err := ioutil.ReadAll(r)
+               if err != nil {
+                       log.Fatal(err)
+               }
+
+               fmt.Printf("%s", b)
+       }
+
+       printall(tee)
+       printall(&buf)
+
+       // Output:
+       // some io.Reader stream to be read
+       // some io.Reader stream to be read
+}
+
+func ExampleSectionReader() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+       s := io.NewSectionReader(r, 5, 17)
+
+       if _, err := io.Copy(os.Stdout, s); err != nil {
+               log.Fatal(err)
+       }
+
+       // Output:
+       // io.Reader stream
+}
+
+func ExampleSectionReader_ReadAt() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+       s := io.NewSectionReader(r, 5, 16)
+
+       buf := make([]byte, 6)
+       if _, err := s.ReadAt(buf, 10); err != nil {
+               log.Fatal(err)
+       }
+
+       fmt.Printf("%s\n", buf)
+
+       // Output:
+       // stream
+}
+
+func ExampleSectionReader_Seek() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+       s := io.NewSectionReader(r, 5, 16)
+
+       if _, err := s.Seek(10, 0); err != nil {
+               log.Fatal(err)
+       }
+
+       buf := make([]byte, 6)
+       if _, err := s.Read(buf); err != nil {
+               log.Fatal(err)
+       }
+
+       fmt.Printf("%s\n", buf)
+
+       // Output:
+       // stream
+}
+
+func ExampleMultiWriter() {
+       r := strings.NewReader("some io.Reader stream to be read\n")
+
+       var buf1, buf2 bytes.Buffer
+       w := io.MultiWriter(&buf1, &buf2)
+
+       if _, err := io.Copy(w, r); err != nil {
+               log.Fatal(err)
+       }
+
+       fmt.Print(buf1.String())
+       fmt.Print(buf2.String())
+
+       // Output:
+       // some io.Reader stream to be read
+       // some io.Reader stream to be read
+}