path: root/docs-src/content/functions/strings.yml

ns: strings
preamble: ''
funcs:
  - name: strings.Abbrev
    description: |
      Abbreviates a string using `...` (ellipses). Takes an optional offset from the beginning of the string, and a maximum final width (including added ellipses).

      _Also see [`strings.Trunc`](#strings-trunc)._
    pipeline: true
    arguments:
      - name: offset
        required: false
        description: offset from the start of the string. Must be `4` or greater for ellipses to be added. Defaults to `0`
      - name: width
        required: true
        description: the desired maximum final width of the string, including ellipses
      - name: input
        required: true
        description: the input string to abbreviate
    examples:
      - |
        $ gomplate -i '{{ "foobarbazquxquux" | strings.Abbrev 9 }}'
        foobar...
        $ gomplate -i '{{ "foobarbazquxquux" | strings.Abbrev 6 9 }}'
        ...baz...
  - name: strings.Contains
    description: |
      Reports whether a substring is contained within a string.
    pipeline: true
    arguments:
      - name: substr
        required: true
        description: the substring to search for
      - name: input
        required: true
        description: the input to search
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{ if (.Env.FOO | strings.Contains "f") }}yes{{else}}no{{end}}
        ```

        ```console
        $ FOO=foo gomplate < input.tmpl
        yes
        $ FOO=bar gomplate < input.tmpl
        no
        ```
  - name: strings.HasPrefix
    description: |
      Tests whether a string begins with a certain prefix.
    pipeline: true
    arguments:
      - name: prefix
        required: true
        description: the prefix to search for
      - name: input
        required: true
        description: the input to search
    examples:
      - |
        $ URL=http://example.com gomplate -i '{{if .Env.URL | strings.HasPrefix "https"}}foo{{else}}bar{{end}}'
        bar
        $ URL=https://example.com gomplate -i '{{if .Env.URL | strings.HasPrefix "https"}}foo{{else}}bar{{end}}'
        foo
  - name: strings.HasSuffix
    description: |
      Tests whether a string ends with a certain suffix.
    pipeline: true
    arguments:
      - name: suffix
        required: true
        description: the suffix to search for
      - name: input
        required: true
        description: the input to search
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{.Env.URL}}{{if not (.Env.URL | strings.HasSuffix ":80")}}:80{{end}}
        ```

        ```console
        $ URL=http://example.com gomplate < input.tmpl
        http://example.com:80
        ```
  - name: strings.Indent
    alias: indent
    description: |
      Indents a string. If the input string has multiple lines, each line will be indented.
    pipeline: true
    arguments:
      - name: width
        required: false
        description: 'number of times to repeat the `indent` string. Default: `1`'
      - name: indent
        required: false
        description: 'the string to indent with. Default: `" "`'
      - name: input
        required: true
        description: the string to indent
    rawExamples:
      - |
        This function can be especially useful when adding YAML snippets into other YAML documents, where indentation is important:

        _`input.tmpl`:_
        ```
        foo:
        {{ `{"bar": {"baz": 2}}` | json | toYAML | strings.Indent "  " }}
        {{- `{"qux": true}` | json | toYAML | strings.Indent 2 }}
          quux:
        {{ `{"quuz": 42}` | json | toYAML | strings.Indent 2 "  " -}}
        ```

        ```console
        $ gomplate -f input.tmpl
        foo:
          bar:
            baz: 2
          qux: true

          quux:
            quuz: 42
        ```
  - name: strings.Sort
    deprecated: Use [`coll.Sort`](../coll/#coll-sort) instead
    description: |
      Returns an alphanumerically-sorted copy of a given string list.
    pipeline: true
    arguments:
      - name: list
        required: true
        description: The list to sort
    examples:
      - |
        $ gomplate -i '{{ (coll.Slice "foo" "bar" "baz") | strings.Sort }}'
        [bar baz foo]
  - name: strings.Split
    description: |
      _Not to be confused with [`split`](#split), which is deprecated._

      Slices `input` into the substrings separated by `separator`, returning a
      slice of the substrings between those separators. If `input` does not
      contain `separator` and `separator` is not empty, returns a single-element
      slice whose only element is `input`.

      If `separator` is empty, it will split after each UTF-8 sequence. If
      both inputs are empty (i.e. `strings.Split "" ""`), it will return an
      empty slice.

      This is equivalent to [`strings.SplitN`](#strings-splitn) with a `count`
      of `-1`.

      Note that the delimiter is not included in the resulting elements.
    pipeline: true
    arguments:
      - name: separator
        required: true
        description: the delimiter to split on, can be multiple characters
      - name: input
        required: true
        description: the input string
    examples:
      - |
        $ gomplate -i '{{range ("Bart,Lisa,Maggie" | strings.Split ",") }}Hello, {{.}}
        {{end}}'
        Hello, Bart
        Hello, Lisa
        Hello, Maggie
      - |
        $ gomplate -i '{{range strings.Split "," "One,Two,Three" }}{{.}}{{"\n"}}{{end}}'
        One
        Two
        Three
  - name: strings.SplitN
    description: |
      _Not to be confused with [`splitN`](#splitn), which is deprecated._

      Slices `input` into the substrings separated by `separator`, returning a
      slice of the substrings between those separators. If `input` does not
      contain `separator` and `separator` is not empty, returns a single-element
      slice whose only element is `input`.

      The `count` determines the number of substrings to return:

      * `count > 0`: at most `count` substrings; the last substring will be the
        unsplit remainder.
      * `count == 0`: the result is nil (zero substrings)
      * `count < 0`: all substrings

      See [`strings.Split`](#strings-split) for more details.
    pipeline: true
    arguments:
      - name: separator
        required: true
        description: the delimiter to split on, can be multiple characters
      - name: count
        required: true
        description: the maximum number of substrings to return
      - name: input
        required: true
        description: the input string
    examples:
      - |
        $ gomplate -i '{{ range ("foo:bar:baz" | strings.SplitN ":" 2) }}{{.}}
        {{end}}'
        foo
        bar:baz
  - name: strings.Quote
    alias: quote
    description: |
      Surrounds an input string with double-quote characters (`"`). If the input is not a string, converts first.

      `"` characters in the input are first escaped with a `\` character.

      This is a convenience function which is equivalent to:

      ```
      {{ print "%q" "input string" }}
      ```
    pipeline: true
    arguments:
      - name: in
        required: true
        description: The input to quote
    examples:
      - |
        $ gomplate -i '{{ "in" | quote }}'
        "in"
        $ gomplate -i '{{ strings.Quote 500 }}'
        "500"
  - name: strings.Repeat
    description: |
      Returns a new string consisting of `count` copies of the input string.

      It errors if `count` is negative or if the length of `input` multiplied by `count` overflows.

      This wraps Go's [`strings.Repeat`](https://golang.org/pkg/strings/#Repeat).
    pipeline: true
    arguments:
      - name: count
        required: true
        description: the number of times to repeat the input
      - name: input
        required: true
        description: the input to repeat
    examples:
      - |
        $ gomplate -i '{{ "hello " | strings.Repeat 5 }}'
        hello hello hello hello hello
  - name: strings.ReplaceAll
    alias: replaceAll
    description: |
      Replaces all occurrences of a given string with another.
    pipeline: true
    arguments:
      - name: old
        required: true
        description: the text to replace
      - name: new
        required: true
        description: the new text to replace with
      - name: input
        required: true
        description: the input to modify
    examples:
      - |
        $ gomplate -i '{{ strings.ReplaceAll "." "-" "172.21.1.42" }}'
        172-21-1-42
        $ gomplate -i '{{ "172.21.1.42" | strings.ReplaceAll "." "-" }}'
        172-21-1-42
  - name: strings.Slug
    description: |
      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.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: the input to "slugify"
    examples:
      - |
        $ gomplate -i '{{ "Hello, world!" | strings.Slug }}'
        hello-world
      - |
        $ echo 'Rock & Roll @ Cafe Wha?' | gomplate -d in=stdin: -i '{{ strings.Slug (include "in") }}'
        rock-and-roll-at-cafe-wha
  - name: strings.ShellQuote
    alias: shellQuote
    description: |
      Given a string, emits a version of that string that will evaluate to its literal data when expanded by any POSIX-compliant shell.

      Given an array or slice, emit a single string which will evaluate to a series of shell words, one per item in that array or slice.
    pipeline: true
    arguments:
      - name: in
        required: true
        description: The input to quote
    examples:
      - |
        $ gomplate -i "{{ coll.Slice \"one word\" \"foo='bar baz'\" | shellQuote }}"
        'one word' 'foo='"'"'bar baz'"'"''
      - |
        $ gomplate -i "{{ strings.ShellQuote \"it's a banana\" }}"
        'it'"'"'s a banana'
  - name: strings.Squote
    alias: squote
    description: |
      Surrounds an input string with a single-quote (apostrophe) character (`'`). If the input is not a string, converts first.

      `'` characters in the input are first escaped in the YAML-style (by repetition: `''`).
    pipeline: true
    arguments:
      - name: in
        required: true
        description: The input to quote
    examples:
      - |
        $ gomplate -i '{{ "in" | squote }}'
        'in'
      - |
        $ gomplate -i "{{ strings.Squote \"it's a banana\" }}"
        'it''s a banana'
  - name: strings.Title
    alias: title
    description: |
      Convert to title-case.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{strings.Title "hello, world!"}}'
        Hello, World!
  - name: strings.ToLower
    alias: toLower
    description: |
      Convert to lower-case.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ echo '{{strings.ToLower "HELLO, WORLD!"}}' | gomplate
        hello, world!
  - name: strings.ToUpper
    alias: toUpper
    description: |
      Convert to upper-case.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{strings.ToUpper "hello, world!"}}'
        HELLO, WORLD!
  - name: strings.Trim
    description: |
      Trims a string by removing the given characters from the beginning and end of
      the string.
    pipeline: true
    arguments:
      - name: cutset
        required: true
        description: the set of characters to cut
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{ "_-foo-_" | strings.Trim "_-" }}
        foo
  - name: strings.TrimPrefix
    description: |
      Returns a string without the provided leading prefix string, if the prefix is present.

      This wraps Go's [`strings.TrimPrefix`](https://golang.org/pkg/strings/#TrimPrefix).
    pipeline: true
    arguments:
      - name: prefix
        required: true
        description: the prefix to trim
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{ "hello, world" | strings.TrimPrefix "hello, " }}'
        world
  - name: strings.TrimSpace
    alias: trimSpace
    description: |
      Trims a string by removing whitespace from the beginning and end of
      the string.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{ "  \n\t foo" | strings.TrimSpace }}'
        foo
  - name: strings.TrimSuffix
    description: |
      Returns a string without the provided trailing suffix string, if the suffix is present.

      This wraps Go's [`strings.TrimSuffix`](https://golang.org/pkg/strings/#TrimSuffix).
    pipeline: true
    arguments:
      - name: suffix
        required: true
        description: the suffix to trim
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{ "hello, world" | strings.TrimSuffix "world" }}jello'
        hello, jello
  - name: strings.Trunc
    description: |
      Returns a string truncated to the given length.

      _Also see [`strings.Abbrev`](#strings-abbrev)._
    pipeline: true
    arguments:
      - name: length
        required: true
        description: the maximum length of the output
      - name: input
        required: true
        description: the input
    examples:
      - |
        $ gomplate -i '{{ "hello, world" | strings.Trunc 5 }}'
        hello
  - name: strings.CamelCase
    description: |
      Converts a sentence to CamelCase, i.e. `The quick brown fox` becomes `TheQuickBrownFox`.

      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.

      See [CamelCase on Wikipedia](https://en.wikipedia.org/wiki/Camel_case) for more details.
    pipeline: true
    arguments:
      - name: in
        required: true
        description: The input
    examples:
      - |
        $ gomplate -i '{{ "Hello, World!" | strings.CamelCase }}'
        HelloWorld
      - |
        $ gomplate -i '{{ "hello jello" | strings.CamelCase }}'
        helloJello
  - name: strings.SnakeCase
    description: |
      Converts a sentence to snake_case, i.e. `The quick brown fox` becomes `The_quick_brown_fox`.

      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.

      See [Snake Case on Wikipedia](https://en.wikipedia.org/wiki/Snake_case) for more details.
    pipeline: true
    arguments:
      - name: in
        required: true
        description: The input
    examples:
      - |
        $ gomplate -i '{{ "Hello, World!" | strings.SnakeCase }}'
        Hello_world
      - |
        $ gomplate -i '{{ "hello jello" | strings.SnakeCase }}'
        hello_jello
  - name: strings.KebabCase
    description: |
      Converts a sentence to kebab-case, i.e. `The quick brown fox` becomes `The-quick-brown-fox`.

      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.

      See [Kebab Case on Wikipedia](https://en.wikipedia.org/wiki/Kebab_case) for more details.
    pipeline: true
    arguments:
      - name: in
        required: true
        description: The input
    examples:
      - |
        $ gomplate -i '{{ "Hello, World!" | strings.KebabCase }}'
        Hello-world
      - |
        $ gomplate -i '{{ "hello jello" | strings.KebabCase }}'
        hello-jello
  - name: strings.WordWrap
    description: |
      Inserts new line breaks into the input string so it ends up with lines that are at most `width` characters wide.

      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.

      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.

      The line-break sequence defaults to `\n` (i.e. the LF/Line Feed character), regardless of OS.
    pipeline: true
    arguments:
      - name: width
        required: false
        description: The desired maximum line length (number of characters - defaults to `80`)
      - name: lbseq
        required: false
        description: The line-break sequence to use (defaults to `\n`)
      - name: in
        required: true
        description: The input
    examples:
      - |
        $ gomplate -i '{{ "Hello, World!" | strings.WordWrap 7 }}'
        Hello,
        World!
      - |
        $ gomplate -i '{{ strings.WordWrap 20 "\\\n" "a string with a long url http://example.com/a/very/long/url which should not be broken" }}'
        a string with a long
        url
        http://example.com/a/very/long/url
        which should not be
        broken
  - name: strings.RuneCount
    description: |
      Return the number of _runes_ (Unicode code-points) contained within the
      input. This is similar to the built-in `len` function, but `len` counts
      the length in _bytes_. The length of an input containing multi-byte
      code-points should therefore be measured with `strings.RuneCount`.

      Inputs will first be converted to strings, and multiple inputs are
      concatenated.

      This wraps Go's [`utf8.RuneCountInString`](https://golang.org/pkg/unicode/utf8/#RuneCountInString)
      function.
    pipeline: true
    arguments:
      - name: input
        required: true
        description: the input(s) to measure
    examples:
      - |
        $ gomplate -i '{{ range (coll.Slice "\u03a9" "\u0030" "\u1430") }}{{ printf "%s is %d bytes and %d runes\n" . (len .) (strings.RuneCount .) }}{{ end }}'
        Ω is 2 bytes and 1 runes
        0 is 1 bytes and 1 runes
        ᐰ is 3 bytes and 1 runes
  - name: contains
    deprecated: Use [`strings.Contains`](#strings-contains) instead
    description: |
      **See [`strings.Contains`](#strings-contains) for a pipeline-compatible version**

      Contains reports whether the second string is contained within the first. Equivalent to
      [strings.Contains](https://golang.org/pkg/strings#Contains)
    pipeline: false
    arguments:
      - name: input
        required: true
        description: the string to search
      - name: substring
        required: true
        description: the string to search for
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{if contains .Env.FOO "f"}}yes{{else}}no{{end}}
        ```

        ```console
        $ FOO=foo gomplate < input.tmpl
        yes
        $ FOO=bar gomplate < input.tmpl
        no
        ```
  - name: hasPrefix
    deprecated: Use [`strings.HasPrefix`](#strings-hasprefix) instead
    description: |
      **See [`strings.HasPrefix`](#strings-hasprefix) for a pipeline-compatible version**

      Tests whether the string begins with a certain substring. Equivalent to
      [strings.HasPrefix](https://golang.org/pkg/strings#HasPrefix)
    pipeline: false
    arguments:
      - name: input
        required: true
        description: the string to search
      - name: prefix
        required: true
        description: the prefix to search for
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{if hasPrefix .Env.URL "https"}}foo{{else}}bar{{end}}
        ```

        ```console
        $ URL=http://example.com gomplate < input.tmpl
        bar
        $ URL=https://example.com gomplate < input.tmpl
        foo
        ```
  - name: hasSuffix
    deprecated: Use [`strings.HasSuffix`](#strings-hassuffix) instead
    description: |
      **See [`strings.HasSuffix`](#strings-hassuffix) for a pipeline-compatible version**

      Tests whether the string ends with a certain substring. Equivalent to
      [strings.HasSuffix](https://golang.org/pkg/strings#HasSuffix)
    pipeline: false
    arguments:
      - name: input
        required: true
        description: the input to search
      - name: suffix
        required: true
        description: the suffix to search for
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        {{.Env.URL}}{{if not (hasSuffix .Env.URL ":80")}}:80{{end}}
        ```

        ```console
        $ URL=http://example.com gomplate < input.tmpl
        http://example.com:80
        ```
  - name: split
    deprecated: Use [`strings.Split`](#strings-split) instead
    description: |
      **See [`strings.Split`](#strings-split) for a pipeline-compatible version**

      Creates a slice by splitting a string on a given delimiter. Equivalent to
      [strings.Split](https://golang.org/pkg/strings#Split)
    pipeline: false
    arguments:
      - name: input
        required: true
        description: the input string
      - name: separator
        required: true
        description: the string sequence to split
    examples:
      - |
        $ gomplate -i '{{range split "Bart,Lisa,Maggie" ","}}Hello, {{.}}
        {{end}}'
        Hello, Bart
        Hello, Lisa
        Hello, Maggie
  - name: splitN
    deprecated: Use [`strings.SplitN`](#strings-splitn) instead
    description: |
      **See [`strings.SplitN`](#strings-splitn) for a pipeline-compatible version**

      Creates a slice by splitting a string on a given delimiter. The count determines
      the number of substrings to return. Equivalent to [strings.SplitN](https://golang.org/pkg/strings#SplitN)
    pipeline: false
    arguments:
      - name: input
        required: true
        description: the input string
      - name: separator
        required: true
        description: the string sequence to split
      - name: count
        required: true
        description: the maximum number of substrings to return
    examples:
      - |
        $ gomplate -i '{{ range splitN "foo:bar:baz" ":" 2 }}{{.}}
        {{end}}'
        foo
        bar:baz
  - name: trim
    deprecated: Use [`strings.Trim`](#strings-trim) instead
    description: |
      **See [`strings.Trim`](#strings-trim) for a pipeline-compatible version**

      Trims a string by removing the given characters from the beginning and end of
      the string. Equivalent to [strings.Trim](https://golang.org/pkg/strings/#Trim)
    pipeline: false
    arguments:
      - name: input
        required: true
        description: the input
      - name: cutset
        required: true
        description: the set of characters to cut
    rawExamples:
      - |
        _`input.tmpl`:_
        ```
        Hello, {{trim .Env.FOO " "}}!
        ```

        ```console
        $ FOO="  world " | gomplate < input.tmpl
        Hello, world!
        ```