strconv: add examples to package

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

src/strconv/atof.go

@@ -2,8 +2,6 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package strconv implements conversions to and from string representations
-// of basic data types.
 package strconv
 
 // decimal to binary floating point conversion.

src/strconv/doc.go

@@ -0,0 +1,57 @@
+// 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 strconv implements conversions to and from string representations
+// of basic data types.
+//
+// Numeric Conversions
+//
+// The most common numeric conversions are Atoi (string to int) and Itoa (int to string).
+//
+//	i, err := strconv.Atoi("-42")
+//	s := strconv.Itoa(-42)
+//
+// These assume decimal and the Go int type.
+//
+// ParseBool, ParseFloat, ParseInt, and ParseUint convert strings to values:
+//
+//	b, err := strconv.ParseBool("true")
+//	f, err := strconv.ParseFloat("3.1415", 64)
+//	i, err := strconv.ParseInt("-42", 10, 64)
+//	u, err := strconv.ParseUint("42", 10, 64)
+//
+// The parse functions return the widest type (float64, int64, and uint64),
+// but if the size argument specifies a narrower width the result can be
+// converted to that narrower type without data loss:
+//
+//	s := "2147483647" // biggest int32
+//	i64, err := strconv.ParseInt(s, 10, 32)
+//	...
+//	i := int32(i64)
+//
+// FormatBool, FormatFloat, FormatInt, and FormatUint convert values to strings:
+//
+// 	s := strconv.FormatBool(true)
+// 	s := strconv.FormatFloat(3.1415, 'E', -1, 64)
+// 	s := strconv.FormatInt(-42, 16)
+// 	s := strconv.FormatUint(42, 16)
+//
+// AppendBool, AppendFloat, AppendInt, and AppendUint are similar but
+// append the formatted value to a destination slice.
+//
+// String Conversions
+//
+// Quote and QuoteToASCII convert strings to quoted Go string literals.
+// The latter guarantees that the result is an ASCII string, by escaping
+// any non-ASCII Unicode with \u:
+//
+//	q := Quote("Hello, 世界")
+//	q := QuoteToASCII("Hello, 世界")
+//
+// QuoteRune and QuoteRuneToASCII are similar but accept runes and
+// return quoted Go rune literals.
+//
+// Unquote and UnquoteChar unquote Go string and rune literals.
+//
+package strconv

src/strconv/example_test.go

@@ -0,0 +1,338 @@
+// 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 strconv_test
+
+import (
+	"fmt"
+	"log"
+	"strconv"
+)
+
+func ExampleAppendBool() {
+	b := []byte("bool:")
+	b = strconv.AppendBool(b, true)
+	fmt.Println(string(b))
+
+	// Output:
+	// bool:true
+}
+
+func ExampleAppendFloat() {
+	b32 := []byte("float32:")
+	b32 = strconv.AppendFloat(b32, 3.1415926535, 'E', -1, 32)
+	fmt.Println(string(b32))
+
+	b64 := []byte("float64:")
+	b64 = strconv.AppendFloat(b64, 3.1415926535, 'E', -1, 64)
+	fmt.Println(string(b64))
+
+	// Output:
+	// float32:3.1415927E+00
+	// float64:3.1415926535E+00
+}
+
+func ExampleAppendInt() {
+	b10 := []byte("int (base 10):")
+	b10 = strconv.AppendInt(b10, -42, 10)
+	fmt.Println(string(b10))
+
+	b16 := []byte("int (base 16):")
+	b16 = strconv.AppendInt(b16, -42, 16)
+	fmt.Println(string(b16))
+
+	// Output:
+	// int (base 10):-42
+	// int (base 16):-2a
+}
+
+func ExampleAppendQuote() {
+	b := []byte("quote:")
+	b = strconv.AppendQuote(b, `"Fran & Freddie's Diner"`)
+	fmt.Println(string(b))
+
+	// Output:
+	// quote:"\"Fran & Freddie's Diner\""
+}
+
+func ExampleAppendQuoteRune() {
+	b := []byte("rune:")
+	b = strconv.AppendQuoteRune(b, '☺')
+	fmt.Println(string(b))
+
+	// Output:
+	// rune:'☺'
+}
+
+func ExampleAppendQuoteRuneToASCII() {
+	b := []byte("rune (ascii):")
+	b = strconv.AppendQuoteRuneToASCII(b, '☺')
+	fmt.Println(string(b))
+
+	// Output:
+	// rune (ascii):'\u263a'
+}
+
+func ExampleAppendQuoteToASCII() {
+	b := []byte("quote (ascii):")
+	b = strconv.AppendQuoteToASCII(b, `"Fran & Freddie's Diner"`)
+	fmt.Println(string(b))
+
+	// Output:
+	// quote (ascii):"\"Fran & Freddie's Diner\""
+}
+
+func ExampleAppendUint() {
+	b10 := []byte("uint (base 10):")
+	b10 = strconv.AppendUint(b10, 42, 10)
+	fmt.Println(string(b10))
+
+	b16 := []byte("uint (base 16):")
+	b16 = strconv.AppendUint(b16, 42, 16)
+	fmt.Println(string(b16))
+
+	// Output:
+	// uint (base 10):42
+	// uint (base 16):2a
+}
+
+func ExampleAtoi() {
+	v := "10"
+	if s, err := strconv.Atoi(v); err == nil {
+		fmt.Printf("%T, %v", s, s)
+	}
+
+	// Output:
+	// int, 10
+}
+
+func ExampleCanBackquote() {
+	fmt.Println(strconv.CanBackquote("Fran & Freddie's Diner ☺"))
+	fmt.Println(strconv.CanBackquote("`can't backquote this`"))
+
+	// Output:
+	// true
+	// false
+}
+
+func ExampleFormatBool() {
+	v := true
+	s := strconv.FormatBool(v)
+	fmt.Printf("%T, %v\n", s, s)
+
+	// Output:
+	// string, true
+}
+
+func ExampleFormatFloat() {
+	v := 3.1415926535
+
+	s32 := strconv.FormatFloat(v, 'E', -1, 32)
+	fmt.Printf("%T, %v\n", s32, s32)
+
+	s64 := strconv.FormatFloat(v, 'E', -1, 64)
+	fmt.Printf("%T, %v\n", s64, s64)
+
+	// Output:
+	// string, 3.1415927E+00
+	// string, 3.1415926535E+00
+}
+
+func ExampleFormatInt() {
+	v := int64(-42)
+
+	s10 := strconv.FormatInt(v, 10)
+	fmt.Printf("%T, %v\n", s10, s10)
+
+	s16 := strconv.FormatInt(v, 16)
+	fmt.Printf("%T, %v\n", s16, s16)
+
+	// Output:
+	// string, -42
+	// string, -2a
+}
+
+func ExampleFormatUint() {
+	v := uint64(42)
+
+	s10 := strconv.FormatUint(v, 10)
+	fmt.Printf("%T, %v\n", s10, s10)
+
+	s16 := strconv.FormatUint(v, 16)
+	fmt.Printf("%T, %v\n", s16, s16)
+
+	// Output:
+	// string, 42
+	// string, 2a
+}
+
+func ExampleIsPrint() {
+	c := strconv.IsPrint('\u263a')
+	fmt.Println(c)
+
+	bel := strconv.IsPrint('\007')
+	fmt.Println(bel)
+
+	// Output:
+	// true
+	// false
+}
+
+func ExampleItoa() {
+	i := 10
+	s := strconv.Itoa(i)
+	fmt.Printf("%T, %v\n", s, s)
+
+	// Output:
+	// string, 10
+}
+
+func ExampleParseBool() {
+	v := "true"
+	if s, err := strconv.ParseBool(v); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+
+	// Output:
+	// bool, true
+}
+
+func ExampleParseFloat() {
+	v := "3.1415926535"
+	if s, err := strconv.ParseFloat(v, 32); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+	if s, err := strconv.ParseFloat(v, 64); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+
+	// Output:
+	// float64, 3.1415927410125732
+	// float64, 3.1415926535
+}
+
+func ExampleParseInt() {
+	v32 := "-354634382"
+	if s, err := strconv.ParseInt(v32, 10, 32); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+	if s, err := strconv.ParseInt(v32, 16, 32); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+
+	v64 := "-3546343826724305832"
+	if s, err := strconv.ParseInt(v64, 10, 64); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+	if s, err := strconv.ParseInt(v64, 16, 64); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+
+	// Output:
+	// int64, -354634382
+	// int64, -3546343826724305832
+}
+
+func ExampleParseUint() {
+	v := "42"
+	if s, err := strconv.ParseUint(v, 10, 32); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+	if s, err := strconv.ParseUint(v, 10, 64); err == nil {
+		fmt.Printf("%T, %v\n", s, s)
+	}
+
+	// Output:
+	// uint64, 42
+	// uint64, 42
+}
+
+func ExampleQuote() {
+	s := strconv.Quote(`"Fran & Freddie's Diner	☺"`)
+	fmt.Println(s)
+
+	// Output:
+	// "\"Fran & Freddie's Diner\t☺\""
+}
+
+func ExampleQuoteRune() {
+	s := strconv.QuoteRune('☺')
+	fmt.Println(s)
+
+	// Output:
+	// '☺'
+}
+
+func ExampleQuoteRuneToASCII() {
+	s := strconv.QuoteRuneToASCII('☺')
+	fmt.Println(s)
+
+	// Output:
+	// '\u263a'
+}
+
+func ExampleQuoteToASCII() {
+	s := strconv.QuoteToASCII(`"Fran & Freddie's Diner	☺"`)
+	fmt.Println(s)
+
+	// Output:
+	// "\"Fran & Freddie's Diner\t\u263a\""
+}
+
+func ExampleUnquote() {
+	test := func(s string) {
+		t, err := strconv.Unquote(s)
+		if err != nil {
+			fmt.Printf("Unquote(%#v): %v\n", s, err)
+		} else {
+			fmt.Printf("Unquote(%#v) = %v\n", s, t)
+		}
+	}
+
+	s := `\"Fran & Freddie's Diner\t\u263a\"\"`
+	// If the string doesn't have quotes, it can't be unquoted.
+	test(s) // invalid syntax
+	test("`" + s + "`")
+	test(`"` + s + `"`)
+	test(`'\u263a'`)
+
+	// Output:
+	// Unquote("\\\"Fran & Freddie's Diner\\t\\u263a\\\"\\\""): invalid syntax
+	// Unquote("`\\\"Fran & Freddie's Diner\\t\\u263a\\\"\\\"`") = \"Fran & Freddie's Diner\t\u263a\"\"
+	// Unquote("\"\\\"Fran & Freddie's Diner\\t\\u263a\\\"\\\"\"") = "Fran & Freddie's Diner	☺""
+	// Unquote("'\\u263a'") = ☺
+}
+
+func ExampleUnquoteChar() {
+	v, mb, t, err := strconv.UnquoteChar(`\"Fran & Freddie's Diner\"`, '"')
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println("value:", string(v))
+	fmt.Println("multibyte:", mb)
+	fmt.Println("tail:", t)
+
+	// Output:
+	// value: "
+	// multibyte: false
+	// tail: Fran & Freddie's Diner\"
+}
+
+func ExampleNumError() {
+	str := "Not a number"
+	if _, err := strconv.ParseFloat(str, 64); err != nil {
+		e := err.(*strconv.NumError)
+		fmt.Println("Func:", e.Func)
+		fmt.Println("Num:", e.Num)
+		fmt.Println("Err:", e.Err)
+		fmt.Println(err)
+	}
+
+	// Output:
+	// Func: ParseFloat
+	// Num: Not a number
+	// Err: invalid syntax
+	// strconv.ParseFloat: parsing "Not a number": invalid syntax
+}

src/strconv/quote_example_test.go

@@ -1,35 +0,0 @@
-// 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 strconv_test
-
-import (
-	"fmt"
-	"strconv"
-)
-
-func ExampleUnquote() {
-	test := func(s string) {
-		t, err := strconv.Unquote(s)
-		if err != nil {
-			fmt.Printf("Unquote(%#v): %v\n", s, err)
-		} else {
-			fmt.Printf("Unquote(%#v) = %v\n", s, t)
-		}
-	}
-
-	s := `cafe\u0301`
-	// If the string doesn't have quotes, it can't be unquoted.
-	test(s) // invalid syntax
-	test("`" + s + "`")
-	test(`"` + s + `"`)
-
-	test(`'\u00e9'`)
-
-	// Output:
-	// Unquote("cafe\\u0301"): invalid syntax
-	// Unquote("`cafe\\u0301`") = cafe\u0301
-	// Unquote("\"cafe\\u0301\"") = café
-	// Unquote("'\\u00e9'") = é
-}