strings functions

strings.Abbrev

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.

Added in gomplate v2.6.0

Usage

strings.Abbrev [offset] width input

input | strings.Abbrev [offset] width

Arguments

name description
offset (optional) offset from the start of the string. Must be 4 or greater for ellipses to be added. Defaults to 0
width (required) the desired maximum final width of the string, including ellipses
input (required) the input string to abbreviate

Examples

$ gomplate -i '{{ "foobarbazquxquux" | strings.Abbrev 9 }}'
foobar...
$ gomplate -i '{{ "foobarbazquxquux" | strings.Abbrev 6 9 }}'
...baz...

strings.Contains

Reports whether a substring is contained within a string.

Added in gomplate v1.9.0

Usage

strings.Contains substr input

input | strings.Contains substr

Arguments

name description
substr (required) the substring to search for
input (required) the input to search

Examples

input.tmpl:

{{ if (.Env.FOO | strings.Contains "f") }}yes{{else}}no{{end}}

$ FOO=foo gomplate < input.tmpl
yes
$ FOO=bar gomplate < input.tmpl
no

strings.HasPrefix

Tests whether a string begins with a certain prefix.

Added in gomplate v1.9.0

Usage

strings.HasPrefix prefix input

input | strings.HasPrefix prefix

Arguments

name description
prefix (required) the prefix to search for
input (required) 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

strings.HasSuffix

Tests whether a string ends with a certain suffix.

Added in gomplate v1.9.0

Usage

strings.HasSuffix suffix input

input | strings.HasSuffix suffix

Arguments

name description
suffix (required) the suffix to search for
input (required) the input to search

Examples

input.tmpl:

{{.Env.URL}}{{if not (.Env.URL | strings.HasSuffix ":80")}}:80{{end}}

$ URL=http://example.com gomplate < input.tmpl
http://example.com:80

strings.Indent

Alias: indent

Indents a string. If the input string has multiple lines, each line will be indented.

Added in gomplate v1.9.0

Usage

strings.Indent [width] [indent] input

input | strings.Indent [width] [indent]

Arguments

name description
width (optional) number of times to repeat the indent string. Default: 1
indent (optional) the string to indent with. Default: " "
input (required) the string to indent

Examples

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 "  " -}}

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

  quux:
    quuz: 42

strings.Sort (deprecated)

Deprecation Notice: Use coll.Sort instead

Returns an alphanumerically-sorted copy of a given string list.

Added in gomplate v2.7.0

Usage

strings.Sort list

list | strings.Sort

Arguments

name description
list (required) The list to sort

Examples

$ gomplate -i '{{ (coll.Slice "foo" "bar" "baz") | strings.Sort }}'
[bar baz foo]

strings.SkipLines(unreleased)

Unreleased: This function is in development, and not yet available in released builds of gomplate.

Skips the given number of lines (each ending in a \n), returning the remainder.

If skip is greater than the number of lines in in, an empty string is returned.

Usage

strings.SkipLines skip in

in | strings.SkipLines skip

Arguments

name description
skip (required) the number of lines to skip - must be a positive number
in (required) the input string

Examples

$ gomplate -i '{{ "foo\nbar\nbaz" | strings.SkipLines 2 }}'
baz

$ gomplate -i '{{ strings.SkipLines 1 "foo\nbar\nbaz" }}'
bar
baz

strings.Split

Not to be confused with 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 with a count of -1.

Note that the delimiter is not included in the resulting elements.

Added in gomplate v1.9.0

Usage

strings.Split separator input

input | strings.Split separator

Arguments

name description
separator (required) the delimiter to split on, can be multiple characters
input (required) 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

strings.SplitN

Not to be confused with 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 for more details.

Added in gomplate v1.9.0

Usage

strings.SplitN separator count input

input | strings.SplitN separator count

Arguments

name description
separator (required) the delimiter to split on, can be multiple characters
count (required) the maximum number of substrings to return
input (required) the input string

Examples

$ gomplate -i '{{ range ("foo:bar:baz" | strings.SplitN ":" 2) }}{{.}}
{{end}}'
foo
bar:baz

strings.Quote

Alias: quote

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" }}

Added in gomplate v3.1.0

Usage

strings.Quote in

in | strings.Quote

Arguments

name description
in (required) The input to quote

Examples

$ gomplate -i '{{ "in" | quote }}'
"in"
$ gomplate -i '{{ strings.Quote 500 }}'
"500"

strings.Repeat

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.

Added in gomplate v2.6.0

Usage

strings.Repeat count input

input | strings.Repeat count

Arguments

name description
count (required) the number of times to repeat the input
input (required) the input to repeat

Examples

$ gomplate -i '{{ "hello " | strings.Repeat 5 }}'
hello hello hello hello hello

strings.ReplaceAll

Alias: replaceAll

Replaces all occurrences of a given string with another.

Added in gomplate v1.9.0

Usage

strings.ReplaceAll old new input

input | strings.ReplaceAll old new

Arguments

name description
old (required) the text to replace
new (required) the new text to replace with
input (required) 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

strings.Slug

Creates a a “slug” from a given string - supports Unicode correctly. This wraps the github.com/gosimple/slug package. See the github.com/gosimple/slug docs for more information.

Added in gomplate v2.6.0

Usage

strings.Slug input

input | strings.Slug

Arguments

name description
input (required) 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

strings.ShellQuote

Alias: shellQuote

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.

Added in gomplate v3.6.0

Usage

strings.ShellQuote in

in | strings.ShellQuote

Arguments

name description
in (required) 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'

strings.Squote

Alias: squote

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: '').

Added in gomplate v3.1.0

Usage

strings.Squote in

in | strings.Squote

Arguments

name description
in (required) The input to quote

Examples

$ gomplate -i '{{ "in" | squote }}'
'in'

$ gomplate -i "{{ strings.Squote \"it's a banana\" }}"
'it''s a banana'

strings.Title

Alias: title

Convert to title-case.

Added in gomplate v1.9.0

Usage

strings.Title input

input | strings.Title

Arguments

name description
input (required) the input

Examples

$ gomplate -i '{{strings.Title "hello, world!"}}'
Hello, World!

strings.ToLower

Alias: toLower

Convert to lower-case.

Added in gomplate v1.9.0

Usage

strings.ToLower input

input | strings.ToLower

Arguments

name description
input (required) the input

Examples

$ echo '{{strings.ToLower "HELLO, WORLD!"}}' | gomplate
hello, world!

strings.ToUpper

Alias: toUpper

Convert to upper-case.

Added in gomplate v1.9.0

Usage

strings.ToUpper input

input | strings.ToUpper

Arguments

name description
input (required) the input

Examples

$ gomplate -i '{{strings.ToUpper "hello, world!"}}'
HELLO, WORLD!

strings.Trim

Trims a string by removing the given characters from the beginning and end of the string.

Added in gomplate v1.9.0

Usage

strings.Trim cutset input

input | strings.Trim cutset

Arguments

name description
cutset (required) the set of characters to cut
input (required) the input

Examples

$ gomplate -i '{{ "_-foo-_" | strings.Trim "_-" }}
foo

strings.TrimPrefix

Returns a string without the provided leading prefix string, if the prefix is present.

This wraps Go’s strings.TrimPrefix.

Added in gomplate v2.5.0

Usage

strings.TrimPrefix prefix input

input | strings.TrimPrefix prefix

Arguments

name description
prefix (required) the prefix to trim
input (required) the input

Examples

$ gomplate -i '{{ "hello, world" | strings.TrimPrefix "hello, " }}'
world

strings.TrimSpace

Alias: trimSpace

Trims a string by removing whitespace from the beginning and end of the string.

Added in gomplate v1.9.0

Usage

strings.TrimSpace input

input | strings.TrimSpace

Arguments

name description
input (required) the input

Examples

$ gomplate -i '{{ "  \n\t foo" | strings.TrimSpace }}'
foo

strings.TrimSuffix

Returns a string without the provided trailing suffix string, if the suffix is present.

This wraps Go’s strings.TrimSuffix.

Added in gomplate v2.6.0

Usage

strings.TrimSuffix suffix input

input | strings.TrimSuffix suffix

Arguments

name description
suffix (required) the suffix to trim
input (required) the input

Examples

$ gomplate -i '{{ "hello, world" | strings.TrimSuffix "world" }}jello'
hello, jello

strings.Trunc

Returns a string truncated to the given length.

Also see strings.Abbrev.

Added in gomplate v2.6.0

Usage

strings.Trunc length input

input | strings.Trunc length

Arguments

name description
length (required) the maximum length of the output
input (required) the input

Examples

$ gomplate -i '{{ "hello, world" | strings.Trunc 5 }}'
hello

strings.CamelCase

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 for more details.

Added in gomplate v3.3.0

Usage

strings.CamelCase in

in | strings.CamelCase

Arguments

name description
in (required) The input

Examples

$ gomplate -i '{{ "Hello, World!" | strings.CamelCase }}'
HelloWorld

$ gomplate -i '{{ "hello jello" | strings.CamelCase }}'
helloJello

strings.SnakeCase

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 for more details.

Added in gomplate v3.3.0

Usage

strings.SnakeCase in

in | strings.SnakeCase

Arguments

name description
in (required) The input

Examples

$ gomplate -i '{{ "Hello, World!" | strings.SnakeCase }}'
Hello_world

$ gomplate -i '{{ "hello jello" | strings.SnakeCase }}'
hello_jello

strings.KebabCase

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 for more details.

Added in gomplate v3.3.0

Usage

strings.KebabCase in

in | strings.KebabCase

Arguments

name description
in (required) The input

Examples

$ gomplate -i '{{ "Hello, World!" | strings.KebabCase }}'
Hello-world

$ gomplate -i '{{ "hello jello" | strings.KebabCase }}'
hello-jello

strings.WordWrap

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.

Added in gomplate v3.3.0

Usage

strings.WordWrap [width] [lbseq] in

in | strings.WordWrap [width] [lbseq]

Arguments

name description
width (optional) The desired maximum line length (number of characters - defaults to 80)
lbseq (optional) The line-break sequence to use (defaults to \n)
in (required) 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

strings.RuneCount

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 function.

Added in gomplate v3.4.0

Usage

strings.RuneCount input

input | strings.RuneCount

Arguments

name description
input (required) 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

contains (deprecated)

Deprecation Notice: Use strings.Contains instead

See strings.Contains for a pipeline-compatible version

Contains reports whether the second string is contained within the first. Equivalent to strings.Contains

Added in gomplate v1.4.0

Usage

contains input substring

Arguments

name description
input (required) the string to search
substring (required) the string to search for

Examples

input.tmpl:

{{if contains .Env.FOO "f"}}yes{{else}}no{{end}}

$ FOO=foo gomplate < input.tmpl
yes
$ FOO=bar gomplate < input.tmpl
no

hasPrefix (deprecated)

Deprecation Notice: Use strings.HasPrefix instead

See strings.HasPrefix for a pipeline-compatible version

Tests whether the string begins with a certain substring. Equivalent to strings.HasPrefix

Added in gomplate v1.4.0

Usage

hasPrefix input prefix

Arguments

name description
input (required) the string to search
prefix (required) the prefix to search for

Examples

input.tmpl:

{{if hasPrefix .Env.URL "https"}}foo{{else}}bar{{end}}

$ URL=http://example.com gomplate < input.tmpl
bar
$ URL=https://example.com gomplate < input.tmpl
foo

hasSuffix (deprecated)

Deprecation Notice: Use strings.HasSuffix instead

See strings.HasSuffix for a pipeline-compatible version

Tests whether the string ends with a certain substring. Equivalent to strings.HasSuffix

Added in gomplate v1.4.0

Usage

hasSuffix input suffix

Arguments

name description
input (required) the input to search
suffix (required) the suffix to search for

Examples

input.tmpl:

{{.Env.URL}}{{if not (hasSuffix .Env.URL ":80")}}:80{{end}}

$ URL=http://example.com gomplate < input.tmpl
http://example.com:80

split (deprecated)

Deprecation Notice: Use strings.Split instead

See strings.Split for a pipeline-compatible version

Creates a slice by splitting a string on a given delimiter. Equivalent to strings.Split

Added in gomplate v1.4.0

Usage

split input separator

Arguments

name description
input (required) the input string
separator (required) the string sequence to split

Examples

$ gomplate -i '{{range split "Bart,Lisa,Maggie" ","}}Hello, {{.}}
{{end}}'
Hello, Bart
Hello, Lisa
Hello, Maggie

splitN (deprecated)

Deprecation Notice: Use strings.SplitN instead

See 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

Added in gomplate v1.7.0

Usage

splitN input separator count

Arguments

name description
input (required) the input string
separator (required) the string sequence to split
count (required) the maximum number of substrings to return

Examples

$ gomplate -i '{{ range splitN "foo:bar:baz" ":" 2 }}{{.}}
{{end}}'
foo
bar:baz

trim (deprecated)

Deprecation Notice: Use strings.Trim instead

See 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

Added in gomplate v1.4.0

Usage

trim input cutset

Arguments

name description
input (required) the input
cutset (required) the set of characters to cut

Examples

input.tmpl:

Hello, {{trim .Env.FOO " "}}!

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