strconv: add examples to package

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

diff --git a/src/strconv/atof.go b/src/strconv/atof.go
index 286206481b25b1fd65794628a50f697ec67c84ed..85b959f1e18bf98c4a26b80610ed56b5c02876c3 100644 (file)
--- a/src/strconv/atof.go
+++ b/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.

diff --git a/src/strconv/doc.go b/src/strconv/doc.go
new file mode 100644 (file)
index 0000000..7bc1e27
--- /dev/null
+++ b/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

diff --git a/src/strconv/example_test.go b/src/strconv/example_test.go
new file mode 100644 (file)
index 0000000..01fbbc0
--- /dev/null
+++ b/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
+}

diff --git a/src/strconv/quote_example_test.go b/src/strconv/quote_example_test.go
deleted file mode 100644 (file)
index 405a57e..0000000
--- a/src/strconv/quote_example_test.go
+++ /dev/null
@@ -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'") = é
-}