io: add examples to functions

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

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
+}