bytes,strings: add some examples

Change-Id: Ic93ad59119f3549c0f13c4f366f71e9d01b88c47
GitHub-Last-Rev: afb518047288976f440d3fe0d65923c1905a9b26
GitHub-Pull-Request: golang/go#57907
Reviewed-on: https://go-review.googlesource.com/c/go/+/462283
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Ian Lance Taylor <iant@google.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Reviewed-by: Cherry Mui <cherryyz@google.com>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Auto-Submit: Ian Lance Taylor <iant@google.com>

src/bytes/example_test.go

@@ -110,6 +110,19 @@ func ExampleBuffer_ReadByte() {
 	// bcde
 }
 
+func ExampleClone() {
+	b := []byte("abc")
+	clone := bytes.Clone(b)
+	fmt.Printf("%s\n", clone)
+	clone[0] = 'd'
+	fmt.Printf("%s\n", b)
+	fmt.Printf("%s\n", clone)
+	// Output:
+	// abc
+	// abc
+	// dbc
+}
+
 func ExampleCompare() {
 	// Interpret Compare's result by comparing it to zero.
 	var a, b []byte
@@ -210,6 +223,30 @@ func ExampleCut() {
 	// Cut("Gopher", "Badger") = "Gopher", "", false
 }
 
+func ExampleCutPrefix() {
+	show := func(s, sep string) {
+		after, found := bytes.CutPrefix([]byte(s), []byte(sep))
+		fmt.Printf("CutPrefix(%q, %q) = %q, %v\n", s, sep, after, found)
+	}
+	show("Gopher", "Go")
+	show("Gopher", "ph")
+	// Output:
+	// CutPrefix("Gopher", "Go") = "pher", true
+	// CutPrefix("Gopher", "ph") = "Gopher", false
+}
+
+func ExampleCutSuffix() {
+	show := func(s, sep string) {
+		before, found := bytes.CutSuffix([]byte(s), []byte(sep))
+		fmt.Printf("CutSuffix(%q, %q) = %q, %v\n", s, sep, before, found)
+	}
+	show("Gopher", "Go")
+	show("Gopher", "er")
+	// Output:
+	// CutSuffix("Gopher", "Go") = "Gopher", false
+	// CutSuffix("Gopher", "er") = "Goph", true
+}
+
 func ExampleEqual() {
 	fmt.Println(bytes.Equal([]byte("Go"), []byte("Go")))
 	fmt.Println(bytes.Equal([]byte("Go"), []byte("C++")))
@@ -347,6 +384,21 @@ func ExampleLastIndexFunc() {
 	// -1
 }
 
+func ExampleMap() {
+	rot13 := func(r rune) rune {
+		switch {
+		case r >= 'A' && r <= 'Z':
+			return 'A' + (r-'A'+13)%26
+		case r >= 'a' && r <= 'z':
+			return 'a' + (r-'a'+13)%26
+		}
+		return r
+	}
+	fmt.Printf("%s\n", bytes.Map(rot13, []byte("'Twas brillig and the slithy gopher...")))
+	// Output:
+	// 'Gjnf oevyyvt naq gur fyvgul tbcure...
+}
+
 func ExampleReader_Len() {
 	fmt.Println(bytes.NewReader([]byte("Hi!")).Len())
 	fmt.Println(bytes.NewReader([]byte("こんにちは!")).Len())
@@ -445,6 +497,16 @@ func ExampleToTitleSpecial() {
 	// ToTitle : AHOJ VÝVOJÁRİ GOLANG
 }
 
+func ExampleToValidUTF8() {
+	fmt.Printf("%s\n", bytes.ToValidUTF8([]byte("abc"), []byte("\uFFFD")))
+	fmt.Printf("%s\n", bytes.ToValidUTF8([]byte("a\xffb\xC0\xAFc\xff"), []byte("")))
+	fmt.Printf("%s\n", bytes.ToValidUTF8([]byte("\xed\xa0\x80"), []byte("abc")))
+	// Output:
+	// abc
+	// abc
+	// abc
+}
+
 func ExampleTrim() {
 	fmt.Printf("[%q]", bytes.Trim([]byte(" !!! Achtung! Achtung! !!! "), "! "))
 	// Output: ["Achtung! Achtung"]

src/strings/example_test.go

@@ -8,8 +8,19 @@ import (
 	"fmt"
 	"strings"
 	"unicode"
+	"unsafe"
 )
 
+func ExampleClone() {
+	s := "abc"
+	clone := strings.Clone(s)
+	fmt.Println(s == clone)
+	fmt.Println(unsafe.StringData(s) == unsafe.StringData(clone))
+	// Output:
+	// true
+	// false
+}
+
 func ExampleBuilder() {
 	var b strings.Builder
 	for i := 3; i >= 1; i-- {
@@ -93,6 +104,30 @@ func ExampleCut() {
 	// Cut("Gopher", "Badger") = "Gopher", "", false
 }
 
+func ExampleCutPrefix() {
+	show := func(s, sep string) {
+		after, found := strings.CutPrefix(s, sep)
+		fmt.Printf("CutPrefix(%q, %q) = %q, %v\n", s, sep, after, found)
+	}
+	show("Gopher", "Go")
+	show("Gopher", "ph")
+	// Output:
+	// CutPrefix("Gopher", "Go") = "pher", true
+	// CutPrefix("Gopher", "ph") = "Gopher", false
+}
+
+func ExampleCutSuffix() {
+	show := func(s, sep string) {
+		before, found := strings.CutSuffix(s, sep)
+		fmt.Printf("CutSuffix(%q, %q) = %q, %v\n", s, sep, before, found)
+	}
+	show("Gopher", "Go")
+	show("Gopher", "er")
+	// Output:
+	// CutSuffix("Gopher", "Go") = "Gopher", false
+	// CutSuffix("Gopher", "er") = "Goph", true
+}
+
 func ExampleEqualFold() {
 	fmt.Println(strings.EqualFold("Go", "go"))
 	fmt.Println(strings.EqualFold("AB", "ab")) // true because comparison uses simple case-folding
@@ -402,3 +437,13 @@ func ExampleTrimRightFunc() {
 	}))
 	// Output: ¡¡¡Hello, Gophers
 }
+
+func ExampleToValidUTF8() {
+	fmt.Printf("%s\n", strings.ToValidUTF8("abc", "\uFFFD"))
+	fmt.Printf("%s\n", strings.ToValidUTF8("a\xffb\xC0\xAFc\xff", ""))
+	fmt.Printf("%s\n", strings.ToValidUTF8("\xed\xa0\x80", "abc"))
+	// Output:
+	// abc
+	// abc
+	// abc
+}