1// Copyright 2012 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5package strings_test
6
7import (
8	"fmt"
9	"strings"
10	"unicode"
11	"unsafe"
12)
13
14func ExampleClone() {
15	s := "abc"
16	clone := strings.Clone(s)
17	fmt.Println(s == clone)
18	fmt.Println(unsafe.StringData(s) == unsafe.StringData(clone))
19	// Output:
20	// true
21	// false
22}
23
24func ExampleBuilder() {
25	var b strings.Builder
26	for i := 3; i >= 1; i-- {
27		fmt.Fprintf(&b, "%d...", i)
28	}
29	b.WriteString("ignition")
30	fmt.Println(b.String())
31
32	// Output: 3...2...1...ignition
33}
34
35func ExampleCompare() {
36	fmt.Println(strings.Compare("a", "b"))
37	fmt.Println(strings.Compare("a", "a"))
38	fmt.Println(strings.Compare("b", "a"))
39	// Output:
40	// -1
41	// 0
42	// 1
43}
44
45func ExampleContains() {
46	fmt.Println(strings.Contains("seafood", "foo"))
47	fmt.Println(strings.Contains("seafood", "bar"))
48	fmt.Println(strings.Contains("seafood", ""))
49	fmt.Println(strings.Contains("", ""))
50	// Output:
51	// true
52	// false
53	// true
54	// true
55}
56
57func ExampleContainsAny() {
58	fmt.Println(strings.ContainsAny("team", "i"))
59	fmt.Println(strings.ContainsAny("fail", "ui"))
60	fmt.Println(strings.ContainsAny("ure", "ui"))
61	fmt.Println(strings.ContainsAny("failure", "ui"))
62	fmt.Println(strings.ContainsAny("foo", ""))
63	fmt.Println(strings.ContainsAny("", ""))
64	// Output:
65	// false
66	// true
67	// true
68	// true
69	// false
70	// false
71}
72
73func ExampleContainsRune() {
74	// Finds whether a string contains a particular Unicode code point.
75	// The code point for the lowercase letter "a", for example, is 97.
76	fmt.Println(strings.ContainsRune("aardvark", 97))
77	fmt.Println(strings.ContainsRune("timeout", 97))
78	// Output:
79	// true
80	// false
81}
82
83func ExampleContainsFunc() {
84	f := func(r rune) bool {
85		return r == 'a' || r == 'e' || r == 'i' || r == 'o' || r == 'u'
86	}
87	fmt.Println(strings.ContainsFunc("hello", f))
88	fmt.Println(strings.ContainsFunc("rhythms", f))
89	// Output:
90	// true
91	// false
92}
93
94func ExampleCount() {
95	fmt.Println(strings.Count("cheese", "e"))
96	fmt.Println(strings.Count("five", "")) // before & after each rune
97	// Output:
98	// 3
99	// 5
100}
101
102func ExampleCut() {
103	show := func(s, sep string) {
104		before, after, found := strings.Cut(s, sep)
105		fmt.Printf("Cut(%q, %q) = %q, %q, %v\n", s, sep, before, after, found)
106	}
107	show("Gopher", "Go")
108	show("Gopher", "ph")
109	show("Gopher", "er")
110	show("Gopher", "Badger")
111	// Output:
112	// Cut("Gopher", "Go") = "", "pher", true
113	// Cut("Gopher", "ph") = "Go", "er", true
114	// Cut("Gopher", "er") = "Goph", "", true
115	// Cut("Gopher", "Badger") = "Gopher", "", false
116}
117
118func ExampleCutPrefix() {
119	show := func(s, sep string) {
120		after, found := strings.CutPrefix(s, sep)
121		fmt.Printf("CutPrefix(%q, %q) = %q, %v\n", s, sep, after, found)
122	}
123	show("Gopher", "Go")
124	show("Gopher", "ph")
125	// Output:
126	// CutPrefix("Gopher", "Go") = "pher", true
127	// CutPrefix("Gopher", "ph") = "Gopher", false
128}
129
130func ExampleCutSuffix() {
131	show := func(s, sep string) {
132		before, found := strings.CutSuffix(s, sep)
133		fmt.Printf("CutSuffix(%q, %q) = %q, %v\n", s, sep, before, found)
134	}
135	show("Gopher", "Go")
136	show("Gopher", "er")
137	// Output:
138	// CutSuffix("Gopher", "Go") = "Gopher", false
139	// CutSuffix("Gopher", "er") = "Goph", true
140}
141
142func ExampleEqualFold() {
143	fmt.Println(strings.EqualFold("Go", "go"))
144	fmt.Println(strings.EqualFold("AB", "ab")) // true because comparison uses simple case-folding
145	fmt.Println(strings.EqualFold("ß", "ss"))  // false because comparison does not use full case-folding
146	// Output:
147	// true
148	// true
149	// false
150}
151
152func ExampleFields() {
153	fmt.Printf("Fields are: %q", strings.Fields("  foo bar  baz   "))
154	// Output: Fields are: ["foo" "bar" "baz"]
155}
156
157func ExampleFieldsFunc() {
158	f := func(c rune) bool {
159		return !unicode.IsLetter(c) && !unicode.IsNumber(c)
160	}
161	fmt.Printf("Fields are: %q", strings.FieldsFunc("  foo1;bar2,baz3...", f))
162	// Output: Fields are: ["foo1" "bar2" "baz3"]
163}
164
165func ExampleHasPrefix() {
166	fmt.Println(strings.HasPrefix("Gopher", "Go"))
167	fmt.Println(strings.HasPrefix("Gopher", "C"))
168	fmt.Println(strings.HasPrefix("Gopher", ""))
169	// Output:
170	// true
171	// false
172	// true
173}
174
175func ExampleHasSuffix() {
176	fmt.Println(strings.HasSuffix("Amigo", "go"))
177	fmt.Println(strings.HasSuffix("Amigo", "O"))
178	fmt.Println(strings.HasSuffix("Amigo", "Ami"))
179	fmt.Println(strings.HasSuffix("Amigo", ""))
180	// Output:
181	// true
182	// false
183	// false
184	// true
185}
186
187func ExampleIndex() {
188	fmt.Println(strings.Index("chicken", "ken"))
189	fmt.Println(strings.Index("chicken", "dmr"))
190	// Output:
191	// 4
192	// -1
193}
194
195func ExampleIndexFunc() {
196	f := func(c rune) bool {
197		return unicode.Is(unicode.Han, c)
198	}
199	fmt.Println(strings.IndexFunc("Hello, 世界", f))
200	fmt.Println(strings.IndexFunc("Hello, world", f))
201	// Output:
202	// 7
203	// -1
204}
205
206func ExampleIndexAny() {
207	fmt.Println(strings.IndexAny("chicken", "aeiouy"))
208	fmt.Println(strings.IndexAny("crwth", "aeiouy"))
209	// Output:
210	// 2
211	// -1
212}
213
214func ExampleIndexByte() {
215	fmt.Println(strings.IndexByte("golang", 'g'))
216	fmt.Println(strings.IndexByte("gophers", 'h'))
217	fmt.Println(strings.IndexByte("golang", 'x'))
218	// Output:
219	// 0
220	// 3
221	// -1
222}
223func ExampleIndexRune() {
224	fmt.Println(strings.IndexRune("chicken", 'k'))
225	fmt.Println(strings.IndexRune("chicken", 'd'))
226	// Output:
227	// 4
228	// -1
229}
230
231func ExampleLastIndex() {
232	fmt.Println(strings.Index("go gopher", "go"))
233	fmt.Println(strings.LastIndex("go gopher", "go"))
234	fmt.Println(strings.LastIndex("go gopher", "rodent"))
235	// Output:
236	// 0
237	// 3
238	// -1
239}
240
241func ExampleLastIndexAny() {
242	fmt.Println(strings.LastIndexAny("go gopher", "go"))
243	fmt.Println(strings.LastIndexAny("go gopher", "rodent"))
244	fmt.Println(strings.LastIndexAny("go gopher", "fail"))
245	// Output:
246	// 4
247	// 8
248	// -1
249}
250
251func ExampleLastIndexByte() {
252	fmt.Println(strings.LastIndexByte("Hello, world", 'l'))
253	fmt.Println(strings.LastIndexByte("Hello, world", 'o'))
254	fmt.Println(strings.LastIndexByte("Hello, world", 'x'))
255	// Output:
256	// 10
257	// 8
258	// -1
259}
260
261func ExampleLastIndexFunc() {
262	fmt.Println(strings.LastIndexFunc("go 123", unicode.IsNumber))
263	fmt.Println(strings.LastIndexFunc("123 go", unicode.IsNumber))
264	fmt.Println(strings.LastIndexFunc("go", unicode.IsNumber))
265	// Output:
266	// 5
267	// 2
268	// -1
269}
270
271func ExampleJoin() {
272	s := []string{"foo", "bar", "baz"}
273	fmt.Println(strings.Join(s, ", "))
274	// Output: foo, bar, baz
275}
276
277func ExampleRepeat() {
278	fmt.Println("ba" + strings.Repeat("na", 2))
279	// Output: banana
280}
281
282func ExampleReplace() {
283	fmt.Println(strings.Replace("oink oink oink", "k", "ky", 2))
284	fmt.Println(strings.Replace("oink oink oink", "oink", "moo", -1))
285	// Output:
286	// oinky oinky oink
287	// moo moo moo
288}
289
290func ExampleReplaceAll() {
291	fmt.Println(strings.ReplaceAll("oink oink oink", "oink", "moo"))
292	// Output:
293	// moo moo moo
294}
295
296func ExampleSplit() {
297	fmt.Printf("%q\n", strings.Split("a,b,c", ","))
298	fmt.Printf("%q\n", strings.Split("a man a plan a canal panama", "a "))
299	fmt.Printf("%q\n", strings.Split(" xyz ", ""))
300	fmt.Printf("%q\n", strings.Split("", "Bernardo O'Higgins"))
301	// Output:
302	// ["a" "b" "c"]
303	// ["" "man " "plan " "canal panama"]
304	// [" " "x" "y" "z" " "]
305	// [""]
306}
307
308func ExampleSplitN() {
309	fmt.Printf("%q\n", strings.SplitN("a,b,c", ",", 2))
310	z := strings.SplitN("a,b,c", ",", 0)
311	fmt.Printf("%q (nil = %v)\n", z, z == nil)
312	// Output:
313	// ["a" "b,c"]
314	// [] (nil = true)
315}
316
317func ExampleSplitAfter() {
318	fmt.Printf("%q\n", strings.SplitAfter("a,b,c", ","))
319	// Output: ["a," "b," "c"]
320}
321
322func ExampleSplitAfterN() {
323	fmt.Printf("%q\n", strings.SplitAfterN("a,b,c", ",", 2))
324	// Output: ["a," "b,c"]
325}
326
327func ExampleTitle() {
328	// Compare this example to the ToTitle example.
329	fmt.Println(strings.Title("her royal highness"))
330	fmt.Println(strings.Title("loud noises"))
331	fmt.Println(strings.Title("хлеб"))
332	// Output:
333	// Her Royal Highness
334	// Loud Noises
335	// Хлеб
336}
337
338func ExampleToTitle() {
339	// Compare this example to the Title example.
340	fmt.Println(strings.ToTitle("her royal highness"))
341	fmt.Println(strings.ToTitle("loud noises"))
342	fmt.Println(strings.ToTitle("хлеб"))
343	// Output:
344	// HER ROYAL HIGHNESS
345	// LOUD NOISES
346	// ХЛЕБ
347}
348
349func ExampleToTitleSpecial() {
350	fmt.Println(strings.ToTitleSpecial(unicode.TurkishCase, "dünyanın ilk borsa yapısı Aizonai kabul edilir"))
351	// Output:
352	// DÜNYANIN İLK BORSA YAPISI AİZONAİ KABUL EDİLİR
353}
354
355func ExampleMap() {
356	rot13 := func(r rune) rune {
357		switch {
358		case r >= 'A' && r <= 'Z':
359			return 'A' + (r-'A'+13)%26
360		case r >= 'a' && r <= 'z':
361			return 'a' + (r-'a'+13)%26
362		}
363		return r
364	}
365	fmt.Println(strings.Map(rot13, "'Twas brillig and the slithy gopher..."))
366	// Output: 'Gjnf oevyyvt naq gur fyvgul tbcure...
367}
368
369func ExampleNewReplacer() {
370	r := strings.NewReplacer("<", "&lt;", ">", "&gt;")
371	fmt.Println(r.Replace("This is <b>HTML</b>!"))
372	// Output: This is &lt;b&gt;HTML&lt;/b&gt;!
373}
374
375func ExampleToUpper() {
376	fmt.Println(strings.ToUpper("Gopher"))
377	// Output: GOPHER
378}
379
380func ExampleToUpperSpecial() {
381	fmt.Println(strings.ToUpperSpecial(unicode.TurkishCase, "örnek iş"))
382	// Output: ÖRNEK İŞ
383}
384
385func ExampleToLower() {
386	fmt.Println(strings.ToLower("Gopher"))
387	// Output: gopher
388}
389
390func ExampleToLowerSpecial() {
391	fmt.Println(strings.ToLowerSpecial(unicode.TurkishCase, "Önnek İş"))
392	// Output: önnek iş
393}
394
395func ExampleTrim() {
396	fmt.Print(strings.Trim("¡¡¡Hello, Gophers!!!", "!¡"))
397	// Output: Hello, Gophers
398}
399
400func ExampleTrimSpace() {
401	fmt.Println(strings.TrimSpace(" \t\n Hello, Gophers \n\t\r\n"))
402	// Output: Hello, Gophers
403}
404
405func ExampleTrimPrefix() {
406	var s = "¡¡¡Hello, Gophers!!!"
407	s = strings.TrimPrefix(s, "¡¡¡Hello, ")
408	s = strings.TrimPrefix(s, "¡¡¡Howdy, ")
409	fmt.Print(s)
410	// Output: Gophers!!!
411}
412
413func ExampleTrimSuffix() {
414	var s = "¡¡¡Hello, Gophers!!!"
415	s = strings.TrimSuffix(s, ", Gophers!!!")
416	s = strings.TrimSuffix(s, ", Marmots!!!")
417	fmt.Print(s)
418	// Output: ¡¡¡Hello
419}
420
421func ExampleTrimFunc() {
422	fmt.Print(strings.TrimFunc("¡¡¡Hello, Gophers!!!", func(r rune) bool {
423		return !unicode.IsLetter(r) && !unicode.IsNumber(r)
424	}))
425	// Output: Hello, Gophers
426}
427
428func ExampleTrimLeft() {
429	fmt.Print(strings.TrimLeft("¡¡¡Hello, Gophers!!!", "!¡"))
430	// Output: Hello, Gophers!!!
431}
432
433func ExampleTrimLeftFunc() {
434	fmt.Print(strings.TrimLeftFunc("¡¡¡Hello, Gophers!!!", func(r rune) bool {
435		return !unicode.IsLetter(r) && !unicode.IsNumber(r)
436	}))
437	// Output: Hello, Gophers!!!
438}
439
440func ExampleTrimRight() {
441	fmt.Print(strings.TrimRight("¡¡¡Hello, Gophers!!!", "!¡"))
442	// Output: ¡¡¡Hello, Gophers
443}
444
445func ExampleTrimRightFunc() {
446	fmt.Print(strings.TrimRightFunc("¡¡¡Hello, Gophers!!!", func(r rune) bool {
447		return !unicode.IsLetter(r) && !unicode.IsNumber(r)
448	}))
449	// Output: ¡¡¡Hello, Gophers
450}
451
452func ExampleToValidUTF8() {
453	fmt.Printf("%s\n", strings.ToValidUTF8("abc", "\uFFFD"))
454	fmt.Printf("%s\n", strings.ToValidUTF8("a\xffb\xC0\xAFc\xff", ""))
455	fmt.Printf("%s\n", strings.ToValidUTF8("\xed\xa0\x80", "abc"))
456	// Output:
457	// abc
458	// abc
459	// abc
460}
461