github.com/wuhuizuo/gomplate@v3.5.0+incompatible/docs-src/content/functions/strings.yml (about) 1 ns: strings 2 preamble: '' 3 funcs: 4 - name: strings.Abbrev 5 description: | 6 Abbreviates a string using `...` (ellipses). Takes an optional offset from the beginning of the string, and a maximum final width (including added ellipses). 7 8 _Also see [`strings.Trunc`](#strings-trunc)._ 9 pipeline: true 10 arguments: 11 - name: offset 12 required: false 13 description: offset from the start of the string. Must be `4` or greater for ellipses to be added. Defaults to `0` 14 - name: width 15 required: true 16 description: the desired maximum final width of the string, including ellipses 17 - name: input 18 required: true 19 description: the input string to abbreviate 20 examples: 21 - | 22 $ gomplate -i '{{ "foobarbazquxquux" | strings.Abbrev 9 }}' 23 foobar... 24 $ gomplate -i '{{ "foobarbazquxquux" | strings.Abbrev 6 9 }}' 25 ...baz... 26 - name: strings.Contains 27 description: | 28 Reports whether a substring is contained within a string. 29 pipeline: true 30 arguments: 31 - name: substr 32 required: true 33 description: the substring to search for 34 - name: input 35 required: true 36 description: the input to search 37 rawExamples: 38 - | 39 _`input.tmpl`:_ 40 ``` 41 {{ if (.Env.FOO | strings.Contains "f") }}yes{{else}}no{{end}} 42 ``` 43 44 ```console 45 $ FOO=foo gomplate < input.tmpl 46 yes 47 $ FOO=bar gomplate < input.tmpl 48 no 49 ``` 50 - name: strings.HasPrefix 51 description: | 52 Tests whether a string begins with a certain prefix. 53 pipeline: true 54 arguments: 55 - name: prefix 56 required: true 57 description: the prefix to search for 58 - name: input 59 required: true 60 description: the input to search 61 examples: 62 - | 63 $ URL=http://example.com gomplate -i '{{if .Env.URL | strings.HasPrefix "https"}}foo{{else}}bar{{end}}' 64 bar 65 $ URL=https://example.com gomplate -i '{{if .Env.URL | strings.HasPrefix "https"}}foo{{else}}bar{{end}}' 66 foo 67 - name: strings.HasSuffix 68 description: | 69 Tests whether a string ends with a certain suffix. 70 pipeline: true 71 arguments: 72 - name: suffix 73 required: true 74 description: the suffix to search for 75 - name: input 76 required: true 77 description: the input to search 78 rawExamples: 79 - | 80 _`input.tmpl`:_ 81 ``` 82 {{.Env.URL}}{{if not (.Env.URL | strings.HasSuffix ":80")}}:80{{end}} 83 ``` 84 85 ```console 86 $ URL=http://example.com gomplate < input.tmpl 87 http://example.com:80 88 ``` 89 - name: strings.Indent 90 alias: indent 91 description: | 92 Indents a string. If the input string has multiple lines, each line will be indented. 93 pipeline: true 94 arguments: 95 - name: width 96 required: false 97 description: 'number of times to repeat the `indent` string. Default: `1`' 98 - name: indent 99 required: false 100 description: 'the string to indent with. Default: `" "`' 101 - name: input 102 required: true 103 description: the string to indent 104 rawExamples: 105 - | 106 This function can be especially useful when adding YAML snippets into other YAML documents, where indentation is important: 107 108 _`input.tmpl`:_ 109 ``` 110 foo: 111 {{ `{"bar": {"baz": 2}}` | json | toYAML | strings.Indent " " }} 112 {{- `{"qux": true}` | json | toYAML | strings.Indent 2 }} 113 quux: 114 {{ `{"quuz": 42}` | json | toYAML | strings.Indent 2 " " -}} 115 ``` 116 117 ```console 118 $ gomplate -f input.tmpl 119 foo: 120 bar: 121 baz: 2 122 qux: true 123 124 quux: 125 quuz: 42 126 ``` 127 - name: strings.Sort 128 deprecated: Use [`coll.Sort`](../coll/#coll-sort) instead 129 description: | 130 Returns an alphanumerically-sorted copy of a given string list. 131 pipeline: true 132 arguments: 133 - name: list 134 required: true 135 description: The list to sort 136 examples: 137 - | 138 $ gomplate -i '{{ (slice "foo" "bar" "baz") | strings.Sort }}' 139 [bar baz foo] 140 - name: strings.Split 141 description: | 142 Creates a slice by splitting a string on a given delimiter. 143 pipeline: true 144 arguments: 145 - name: separator 146 required: true 147 description: the string sequence to split 148 - name: input 149 required: true 150 description: the input string 151 examples: 152 - | 153 $ gomplate -i '{{range ("Bart,Lisa,Maggie" | strings.Split ",") }}Hello, {{.}}{{end}}' 154 Hello, Bart 155 Hello, Lisa 156 Hello, Maggie 157 - name: strings.SplitN 158 description: | 159 Creates a slice by splitting a string on a given delimiter. The count determines 160 the number of substrings to return. 161 pipeline: true 162 arguments: 163 - name: separator 164 required: true 165 description: the string sequence to split 166 - name: count 167 required: true 168 description: the maximum number of substrings to return 169 - name: input 170 required: true 171 description: the input string 172 examples: 173 - | 174 $ gomplate -i '{{ range ("foo:bar:baz" | strings.SplitN ":" 2) }}{{.}}{{end}}' 175 foo 176 bar:baz 177 - name: strings.Quote 178 alias: quote 179 description: | 180 Surrounds an input string with double-quote characters (`"`). If the input is not a string, converts first. 181 182 `"` characters in the input are first escaped with a `\` character. 183 184 This is a convenience function which is equivalent to: 185 186 ``` 187 {{ print "%q" "input string" }} 188 ``` 189 pipeline: true 190 arguments: 191 - name: in 192 required: true 193 description: The input to quote 194 examples: 195 - | 196 $ gomplate -i '{{ "in" | quote }}' 197 "in" 198 $ gomplate -i '{{ strings.Quote 500 }}' 199 "500" 200 - name: strings.Repeat 201 description: | 202 Returns a new string consisting of `count` copies of the input string. 203 204 It errors if `count` is negative or if the length of `input` multiplied by `count` overflows. 205 206 This wraps Go's [`strings.Repeat`](https://golang.org/pkg/strings/#Repeat). 207 pipeline: true 208 arguments: 209 - name: count 210 required: true 211 description: the number of times to repeat the input 212 - name: input 213 required: true 214 description: the input to repeat 215 examples: 216 - | 217 $ gomplate -i '{{ "hello " | strings.Repeat 5 }}' 218 hello hello hello hello hello 219 - name: strings.ReplaceAll 220 alias: replaceAll 221 description: | 222 Replaces all occurrences of a given string with another. 223 pipeline: true 224 arguments: 225 - name: old 226 required: true 227 description: the text to replace 228 - name: new 229 required: true 230 description: the new text to replace with 231 - name: input 232 required: true 233 description: the input to modify 234 examples: 235 - | 236 $ gomplate -i '{{ strings.ReplaceAll "." "-" "172.21.1.42" }}' 237 172-21-1-42 238 $ gomplate -i '{{ "172.21.1.42" | strings.ReplaceAll "." "-" }}' 239 172-21-1-42 240 - name: strings.Slug 241 description: | 242 Creates a a "slug" from a given string - supports Unicode correctly. This wraps the [github.com/gosimple/slug](https://github.com/gosimple/slug) package. See [the github.com/gosimple/slug docs](https://godoc.org/github.com/gosimple/slug) for more information. 243 pipeline: true 244 arguments: 245 - name: input 246 required: true 247 description: the input to "slugify" 248 examples: 249 - | 250 $ gomplate -i '{{ "Hello, world!" | strings.Slug }}' 251 hello-world 252 - | 253 $ echo 'Rock & Roll @ Cafe Wha?' | gomplate -d in=stdin: -i '{{ strings.Slug (include "in") }}' 254 rock-and-roll-at-cafe-wha 255 - name: strings.Squote 256 alias: squote 257 description: | 258 Surrounds an input string with a single-quote (apostrophe) character (`'`). If the input is not a string, converts first. 259 260 `'` characters in the input are first escaped in the YAML-style (by repetition: `''`). 261 pipeline: true 262 arguments: 263 - name: in 264 required: true 265 description: The input to quote 266 examples: 267 - | 268 $ gomplate -i '{{ "in" | squote }}' 269 'in' 270 - | 271 $ gomplate -i "{{ strings.Squote \"it's a banana\" }}" 272 'it''s a banana' 273 - name: strings.Title 274 alias: title 275 description: | 276 Convert to title-case. 277 pipeline: true 278 arguments: 279 - name: input 280 required: true 281 description: the input 282 examples: 283 - | 284 $ gomplate -i '{{strings.Title "hello, world!"}}' 285 Hello, World! 286 - name: strings.ToLower 287 alias: toLower 288 description: | 289 Convert to lower-case. 290 pipeline: true 291 arguments: 292 - name: input 293 required: true 294 description: the input 295 examples: 296 - | 297 $ echo '{{strings.ToLower "HELLO, WORLD!"}}' | gomplate 298 hello, world! 299 - name: strings.ToUpper 300 alias: toUpper 301 description: | 302 Convert to upper-case. 303 pipeline: true 304 arguments: 305 - name: input 306 required: true 307 description: the input 308 examples: 309 - | 310 $ gomplate -i '{{strings.ToUpper "hello, world!"}}' 311 HELLO, WORLD! 312 - name: strings.Trim 313 description: | 314 Trims a string by removing the given characters from the beginning and end of 315 the string. 316 pipeline: true 317 arguments: 318 - name: cutset 319 required: true 320 description: the set of characters to cut 321 - name: input 322 required: true 323 description: the input 324 examples: 325 - | 326 $ gomplate -i '{{ "_-foo-_" | strings.Trim "_-" }} 327 foo 328 - name: strings.TrimPrefix 329 description: | 330 Returns a string without the provided leading prefix string, if the prefix is present. 331 332 This wraps Go's [`strings.TrimPrefix`](https://golang.org/pkg/strings/#TrimPrefix). 333 pipeline: true 334 arguments: 335 - name: prefix 336 required: true 337 description: the prefix to trim 338 - name: input 339 required: true 340 description: the input 341 examples: 342 - | 343 $ gomplate -i '{{ "hello, world" | strings.TrimPrefix "hello, " }}' 344 world 345 - name: strings.TrimSpace 346 alias: trimSpace 347 description: | 348 Trims a string by removing whitespace from the beginning and end of 349 the string. 350 pipeline: true 351 arguments: 352 - name: input 353 required: true 354 description: the input 355 examples: 356 - | 357 $ gomplate -i '{{ " \n\t foo" | strings.TrimSpace }}' 358 foo 359 - name: strings.TrimSuffix 360 description: | 361 Returns a string without the provided trailing suffix string, if the suffix is present. 362 363 This wraps Go's [`strings.TrimSuffix`](https://golang.org/pkg/strings/#TrimSuffix). 364 pipeline: true 365 arguments: 366 - name: suffix 367 required: true 368 description: the suffix to trim 369 - name: input 370 required: true 371 description: the input 372 examples: 373 - | 374 $ gomplate -i '{{ "hello, world" | strings.TrimSuffix "world" }}jello' 375 hello, jello 376 - name: strings.Trunc 377 description: | 378 Returns a string truncated to the given length. 379 380 _Also see [`strings.Abbrev`](#strings-abbrev)._ 381 pipeline: true 382 arguments: 383 - name: length 384 required: true 385 description: the maximum length of the output 386 - name: input 387 required: true 388 description: the input 389 examples: 390 - | 391 $ gomplate -i '{{ "hello, world" | strings.Trunc 5 }}' 392 hello 393 - name: strings.CamelCase 394 description: | 395 Converts a sentence to CamelCase, i.e. `The quick brown fox` becomes `TheQuickBrownFox`. 396 397 All non-alphanumeric characters are stripped, and the beginnings of words are upper-cased. If the input begins with a lower-case letter, the result will also begin with a lower-case letter. 398 399 See [CamelCase on Wikipedia](https://en.wikipedia.org/wiki/Camel_case) for more details. 400 pipeline: true 401 arguments: 402 - name: in 403 required: true 404 description: The input 405 examples: 406 - | 407 $ gomplate -i '{{ "Hello, World!" | strings.CamelCase }}' 408 HelloWorld 409 - | 410 $ gomplate -i '{{ "hello jello" | strings.CamelCase }}' 411 helloJello 412 - name: strings.SnakeCase 413 description: | 414 Converts a sentence to snake_case, i.e. `The quick brown fox` becomes `The_quick_brown_fox`. 415 416 All non-alphanumeric characters are stripped, and spaces are replaced with an underscore (`_`). If the input begins with a lower-case letter, the result will also begin with a lower-case letter. 417 418 See [Snake Case on Wikipedia](https://en.wikipedia.org/wiki/Snake_case) for more details. 419 pipeline: true 420 arguments: 421 - name: in 422 required: true 423 description: The input 424 examples: 425 - | 426 $ gomplate -i '{{ "Hello, World!" | strings.SnakeCase }}' 427 Hello_world 428 - | 429 $ gomplate -i '{{ "hello jello" | strings.SnakeCase }}' 430 hello_jello 431 - name: strings.KebabCase 432 description: | 433 Converts a sentence to kebab-case, i.e. `The quick brown fox` becomes `The-quick-brown-fox`. 434 435 All non-alphanumeric characters are stripped, and spaces are replaced with a hyphen (`-`). If the input begins with a lower-case letter, the result will also begin with a lower-case letter. 436 437 See [Kebab Case on Wikipedia](https://en.wikipedia.org/wiki/Kebab_case) for more details. 438 pipeline: true 439 arguments: 440 - name: in 441 required: true 442 description: The input 443 examples: 444 - | 445 $ gomplate -i '{{ "Hello, World!" | strings.KebabCase }}' 446 Hello-world 447 - | 448 $ gomplate -i '{{ "hello jello" | strings.KebabCase }}' 449 hello-jello 450 - name: strings.WordWrap 451 description: | 452 Inserts new line breaks into the input string so it ends up with lines that are at most `width` characters wide. 453 454 The line-breaking algorithm is _naïve_ and _greedy_: lines are only broken between words (i.e. on whitespace characters), and no effort is made to "smooth" the line endings. 455 456 When words that are longer than the desired width are encountered (e.g. long URLs), they are not broken up. Correctness is valued above line length. 457 458 The line-break sequence defaults to `\n` (i.e. the LF/Line Feed character), regardless of OS. 459 pipeline: true 460 arguments: 461 - name: width 462 required: false 463 description: The desired maximum line length (number of characters - defaults to `80`) 464 - name: lbseq 465 required: false 466 description: The line-break sequence to use (defaults to `\n`) 467 - name: in 468 required: true 469 description: The input 470 examples: 471 - | 472 $ gomplate -i '{{ "Hello, World!" | strings.WordWrap 7 }}' 473 Hello, 474 World! 475 - | 476 $ gomplate -i '{{ strings.WordWrap 20 "\\\n" "a string with a long url http://example.com/a/very/long/url which should not be broken" }}' 477 a string with a long 478 url 479 http://example.com/a/very/long/url 480 which should not be 481 broken 482 - name: strings.RuneCount 483 description: | 484 Return the number of _runes_ (Unicode code-points) contained within the 485 input. This is similar to the built-in `len` function, but `len` counts 486 the length in _bytes_. The length of an input containing multi-byte 487 code-points should therefore be measured with `strings.RuneCount`. 488 489 Inputs will first be converted to strings, and multiple inputs are 490 concatenated. 491 492 This wraps Go's [`utf8.RuneCountInString`](https://golang.org/pkg/unicode/utf8/#RuneCountInString) 493 function. 494 pipeline: true 495 arguments: 496 - name: input 497 required: true 498 description: the input(s) to measure 499 examples: 500 - | 501 $ gomplate -i '{{ range (slice "\u03a9" "\u0030" "\u1430") }}{{ printf "%s is %d bytes and %d runes\n" . (len .) (strings.RuneCount .) }}{{ end }}' 502 Ω is 2 bytes and 1 runes 503 0 is 1 bytes and 1 runes 504 ᐰ is 3 bytes and 1 runes 505 - name: contains 506 description: | 507 **See [`strings.Contains`](#strings-contains) for a pipeline-compatible version** 508 509 Contains reports whether the second string is contained within the first. Equivalent to 510 [strings.Contains](https://golang.org/pkg/strings#Contains) 511 pipeline: false 512 arguments: 513 - name: input 514 required: true 515 description: the string to search 516 - name: substring 517 required: true 518 description: the string to search for 519 rawExamples: 520 - | 521 _`input.tmpl`:_ 522 ``` 523 {{if contains .Env.FOO "f"}}yes{{else}}no{{end}} 524 ``` 525 526 ```console 527 $ FOO=foo gomplate < input.tmpl 528 yes 529 $ FOO=bar gomplate < input.tmpl 530 no 531 ``` 532 - name: hasPrefix 533 description: | 534 **See [`strings.HasPrefix`](#strings-hasprefix) for a pipeline-compatible version** 535 536 Tests whether the string begins with a certain substring. Equivalent to 537 [strings.HasPrefix](https://golang.org/pkg/strings#HasPrefix) 538 pipeline: false 539 arguments: 540 - name: input 541 required: true 542 description: the string to search 543 - name: prefix 544 required: true 545 description: the prefix to search for 546 rawExamples: 547 - | 548 _`input.tmpl`:_ 549 ``` 550 {{if hasPrefix .Env.URL "https"}}foo{{else}}bar{{end}} 551 ``` 552 553 ```console 554 $ URL=http://example.com gomplate < input.tmpl 555 bar 556 $ URL=https://example.com gomplate < input.tmpl 557 foo 558 ``` 559 - name: hasSuffix 560 description: | 561 **See [`strings.HasSuffix`](#strings-hassuffix) for a pipeline-compatible version** 562 563 Tests whether the string ends with a certain substring. Equivalent to 564 [strings.HasSuffix](https://golang.org/pkg/strings#HasSuffix) 565 pipeline: false 566 arguments: 567 - name: input 568 required: true 569 description: the input to search 570 - name: suffix 571 required: true 572 description: the suffix to search for 573 rawExamples: 574 - | 575 _`input.tmpl`:_ 576 ``` 577 {{.Env.URL}}{{if not (hasSuffix .Env.URL ":80")}}:80{{end}} 578 ``` 579 580 ```console 581 $ URL=http://example.com gomplate < input.tmpl 582 http://example.com:80 583 ``` 584 - name: split 585 description: | 586 **See [`strings.Split`](#strings-split) for a pipeline-compatible version** 587 588 Creates a slice by splitting a string on a given delimiter. Equivalent to 589 [strings.Split](https://golang.org/pkg/strings#Split) 590 pipeline: false 591 arguments: 592 - name: input 593 required: true 594 description: the input string 595 - name: separator 596 required: true 597 description: the string sequence to split 598 examples: 599 - | 600 $ gomplate -i '{{range split "Bart,Lisa,Maggie" ","}}Hello, {{.}}{{end}}' 601 Hello, Bart 602 Hello, Lisa 603 Hello, Maggie 604 - name: splitN 605 description: | 606 **See [`strings.SplitN`](#strings-splitn) for a pipeline-compatible version** 607 608 Creates a slice by splitting a string on a given delimiter. The count determines 609 the number of substrings to return. Equivalent to [strings.SplitN](https://golang.org/pkg/strings#SplitN) 610 pipeline: false 611 arguments: 612 - name: input 613 required: true 614 description: the input string 615 - name: separator 616 required: true 617 description: the string sequence to split 618 - name: count 619 required: true 620 description: the maximum number of substrings to return 621 examples: 622 - | 623 $ gomplate -i '{{ range splitN "foo:bar:baz" ":" 2 }}{{.}}{{end}}' 624 foo 625 bar:baz 626 - name: trim 627 description: | 628 **See [`strings.Trim`](#strings-trim) for a pipeline-compatible version** 629 630 Trims a string by removing the given characters from the beginning and end of 631 the string. Equivalent to [strings.Trim](https://golang.org/pkg/strings/#Trim) 632 pipeline: false 633 arguments: 634 - name: input 635 required: true 636 description: the input 637 - name: cutset 638 required: true 639 description: the set of characters to cut 640 rawExamples: 641 - | 642 _`input.tmpl`:_ 643 ``` 644 Hello, {{trim .Env.FOO " "}}! 645 ``` 646 647 ```console 648 $ FOO=" world " | gomplate < input.tmpl 649 Hello, world! 650 ```