diff options
Diffstat (limited to 'docs/content/en/functions/strings')
32 files changed, 858 insertions, 0 deletions
diff --git a/docs/content/en/functions/strings/Chomp.md b/docs/content/en/functions/strings/Chomp.md new file mode 100644 index 000000000..8024758ba --- /dev/null +++ b/docs/content/en/functions/strings/Chomp.md @@ -0,0 +1,28 @@ +--- +title: strings.Chomp +description: Returns the given string, removing all trailing newline characters and carriage returns. +categories: [] +keywords: [] +action: + aliases: [chomp] + related: + - functions/strings/Trim + - functions/strings/TrimSpace + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix + returnType: any + signatures: [strings.Chomp STRING] +aliases: [/functions/chomp] +--- + +If the argument is of type `template.HTML`, returns `template.HTML`, else returns a `string`. + +```go-html-template +{{ chomp "foo\n" }} → foo +{{ chomp "foo\n\n" }} → foo + +{{ chomp "foo\r\n" }} → foo +{{ chomp "foo\r\n\r\n" }} → foo +``` diff --git a/docs/content/en/functions/strings/Contains.md b/docs/content/en/functions/strings/Contains.md new file mode 100644 index 000000000..0344b2981 --- /dev/null +++ b/docs/content/en/functions/strings/Contains.md @@ -0,0 +1,27 @@ +--- +title: strings.Contains +description: Reports whether the given string contains the given substring. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In + returnType: bool + signatures: [strings.Contains STRING SUBSTRING] +aliases: [/functions/strings.contains] +--- + +```go-html-template +{{ strings.Contains "Hugo" "go" }} → true +``` + +The check is case sensitive: + +```go-html-template +{{ strings.Contains "Hugo" "Go" }} → false +``` diff --git a/docs/content/en/functions/strings/ContainsAny.md b/docs/content/en/functions/strings/ContainsAny.md new file mode 100644 index 000000000..f331d09f7 --- /dev/null +++ b/docs/content/en/functions/strings/ContainsAny.md @@ -0,0 +1,27 @@ +--- +title: strings.ContainsAny +description: Reports whether the given string contains any character within the given set. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Contains + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In + returnType: bool + signatures: [strings.ContainsAny STRING SET] +aliases: [/functions/strings.containsany] +--- + +```go-html-template +{{ strings.ContainsAny "Hugo" "gm" }} → true +``` + +The check is case sensitive: + +```go-html-template +{{ strings.ContainsAny "Hugo" "Gm" }} → false +``` diff --git a/docs/content/en/functions/strings/ContainsNonSpace.md b/docs/content/en/functions/strings/ContainsNonSpace.md new file mode 100644 index 000000000..81e11a5ba --- /dev/null +++ b/docs/content/en/functions/strings/ContainsNonSpace.md @@ -0,0 +1,29 @@ +--- +title: strings.ContainsNonSpace +description: Reports whether the given string contains any non-space characters as defined by Unicode. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/HasPrefix + - functions/strings/HasSuffix + - functions/collections/In + returnType: bool + signatures: [strings.ContainsNonSpace STRING] +aliases: [/functions/strings.containsnonspace] +--- + +{{< new-in 0.111.0 >}} + +Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category. + +[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs + +```go-html-template +{{ strings.ContainsNonSpace "\n" }} → false +{{ strings.ContainsNonSpace " " }} → false +{{ strings.ContainsNonSpace "\n abc" }} → true +``` diff --git a/docs/content/en/functions/strings/Count.md b/docs/content/en/functions/strings/Count.md new file mode 100644 index 000000000..43b5baeff --- /dev/null +++ b/docs/content/en/functions/strings/Count.md @@ -0,0 +1,25 @@ +--- +title: strings.Count +description: Returns the number of non-overlapping instances of the given substring within the given string. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/len + - functions/strings/CountRunes + - functions/strings/CountWords + - functions/strings/RuneCount + returnType: int + signatures: [strings.Count SUBSTR STRING] +aliases: [/functions/strings.count] +--- + +If `SUBSTR` is an empty string, this function returns 1 plus the number of Unicode code points in `STRING`. + +```go-html-template +{{ "aaabaab" | strings.Count "a" }} → 5 +{{ "aaabaab" | strings.Count "aa" }} → 2 +{{ "aaabaab" | strings.Count "aaa" }} → 1 +{{ "aaabaab" | strings.Count "" }} → 8 +``` diff --git a/docs/content/en/functions/strings/CountRunes.md b/docs/content/en/functions/strings/CountRunes.md new file mode 100644 index 000000000..87d9da680 --- /dev/null +++ b/docs/content/en/functions/strings/CountRunes.md @@ -0,0 +1,24 @@ +--- +title: strings.CountRunes +description: Returns the number of runes in the given string excluding whitespace. +categories: [] +keywords: [] +action: + aliases: [countrunes] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountWords + - functions/strings/RuneCount + returnType: int + signatures: [strings.CountRunes INPUT] +aliases: [/functions/countrunes] +--- + +In contrast with the [`strings.RuneCount`] function, which counts every rune in a string, `strings.CountRunes` excludes whitespace. + +```go-html-template +{{ "Hello, 世界" | strings.CountRunes }} → 8 +``` + +[`strings.RuneCount`]: /functions/strings/runecount/ diff --git a/docs/content/en/functions/strings/CountWords.md b/docs/content/en/functions/strings/CountWords.md new file mode 100644 index 000000000..3e4ec0465 --- /dev/null +++ b/docs/content/en/functions/strings/CountWords.md @@ -0,0 +1,20 @@ +--- +title: strings.CountWords +description: Returns the number of words in the given string. +categories: [] +keywords: [] +action: + aliases: [countwords] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/RuneCount + returnType: int + signatures: [strings.CountWords INPUT] +aliases: [/functions/countwords] +--- + +```go-html-template +{{ "Hugo is a static site generator." | countwords }} → 6 +``` diff --git a/docs/content/en/functions/strings/Diff/diff-screen-capture.png b/docs/content/en/functions/strings/Diff/diff-screen-capture.png Binary files differnew file mode 100644 index 000000000..62baa4563 --- /dev/null +++ b/docs/content/en/functions/strings/Diff/diff-screen-capture.png diff --git a/docs/content/en/functions/strings/Diff/index.md b/docs/content/en/functions/strings/Diff/index.md new file mode 100644 index 000000000..da172bbeb --- /dev/null +++ b/docs/content/en/functions/strings/Diff/index.md @@ -0,0 +1,33 @@ +--- +title: strings.Diff +description: Returns an anchored diff of the two texts OLD and NEW in the unified diff format. If OLD and NEW are identical, returns an empty string. +categories: [] +keywords: [] +action: + related: [] + returnType: string + signatures: [strings.Diff OLDNAME OLD NEWNAME NEW] +--- + +{{< new-in 0.125.0 >}} + +Use `strings.Diff` to compare two strings and render a highlighted diff: + +```go-html-template +{{ $want := ` +<p>The product of 6 and 7 is 42.</p> +<p>The product of 7 and 6 is 42.</p> +`}} + +{{ $got := ` +<p>The product of 6 and 7 is 42.</p> +<p>The product of 7 and 6 is 13.</p> +`}} + +{{ $diff := strings.Diff "want" $want "got" $got }} +{{ transform.Highlight $diff "diff" }} +``` + +Rendered: + + diff --git a/docs/content/en/functions/strings/FindRESubmatch.md b/docs/content/en/functions/strings/FindRESubmatch.md new file mode 100644 index 000000000..3feb15bbd --- /dev/null +++ b/docs/content/en/functions/strings/FindRESubmatch.md @@ -0,0 +1,90 @@ +--- +title: strings.FindRESubmatch +description: Returns a slice of all successive matches of the regular expression. Each element is a slice of strings holding the text of the leftmost match of the regular expression and the matches, if any, of its subexpressions. +categories: [] +keywords: [] +action: + aliases: [findRESubmatch] + related: + - functions/strings/FindRE + - functions/strings/Replace + - functions/strings/ReplaceRE + returnType: '[][]string' + signatures: ['strings.FindRESubmatch PATTERN INPUT [LIMIT]'] +aliases: [/functions/findresubmatch] +--- + +By default, `findRESubmatch` finds all matches. You can limit the number of matches with an optional LIMIT argument. A return value of nil indicates no match. + +{{% include "functions/_common/regular-expressions.md" %}} + +## Demonstrative examples + +```go-html-template +{{ findRESubmatch `a(x*)b` "-ab-" }} → [["ab" ""]] +{{ findRESubmatch `a(x*)b` "-axxb-" }} → [["axxb" "xx"]] +{{ findRESubmatch `a(x*)b` "-ab-axb-" }} → [["ab" ""] ["axb" "x"]] +{{ findRESubmatch `a(x*)b` "-axxb-ab-" }} → [["axxb" "xx"] ["ab" ""]] +{{ findRESubmatch `a(x*)b` "-axxb-ab-" 1 }} → [["axxb" "xx"]] +``` + +## Practical example + +This Markdown: + +```text +- [Example](https://example.org) +- [Hugo](https://gohugo.io) +``` + +Produces this HTML: + +```html +<ul> + <li><a href="https://example.org">Example</a></li> + <li><a href="https://gohugo.io">Hugo</a></li> +</ul> +``` + +To match the anchor elements, capturing the link destination and text: + +```go-html-template +{{ $regex := `<a\s*href="(.+?)">(.+?)</a>` }} +{{ $matches := findRESubmatch $regex .Content }} +``` + +Viewed as JSON, the data structure of `$matches` in the code above is: + +```json +[ + [ + "<a href=\"https://example.org\"></a>Example</a>", + "https://example.org", + "Example" + ], + [ + "<a href=\"https://gohugo.io\">Hugo</a>", + "https://gohugo.io", + "Hugo" + ] +] +``` + +To render the `href` attributes: + +```go-html-template +{{ range $matches }} + {{ index . 1 }} +{{ end }} +``` + +Result: + +```text +https://example.org +https://gohugo.io +``` + +{{% note %}} +You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. +{{% /note %}} diff --git a/docs/content/en/functions/strings/FindRe.md b/docs/content/en/functions/strings/FindRe.md new file mode 100644 index 000000000..861f38a12 --- /dev/null +++ b/docs/content/en/functions/strings/FindRe.md @@ -0,0 +1,36 @@ +--- +title: strings.FindRE +description: Returns a slice of strings that match the regular expression. +categories: [] +keywords: [] +action: + aliases: [findRE] + related: + - functions/strings/FindRESubmatch + - functions/strings/Replace + - functions/strings/ReplaceRE + returnType: '[]string' + signatures: ['strings.FindRE PATTERN INPUT [LIMIT]'] +aliases: [/functions/findre] +--- +By default, `findRE` finds all matches. You can limit the number of matches with an optional LIMIT argument. + +{{% include "functions/_common/regular-expressions.md" %}} + +This example returns a slice of all second level headings (`h2` elements) within the rendered `.Content`: + +```go-html-template +{{ findRE `(?s)<h2.*?>.*?</h2>` .Content }} +``` + +The `s` flag causes `.` to match `\n` as well, allowing us to find an `h2` element that contains newlines. + +To limit the number of matches to one: + +```go-html-template +{{ findRE `(?s)<h2.*?>.*?</h2>` .Content 1 }} +``` + +{{% note %}} +You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. +{{% /note %}} diff --git a/docs/content/en/functions/strings/FirstUpper.md b/docs/content/en/functions/strings/FirstUpper.md new file mode 100644 index 000000000..8826b4f18 --- /dev/null +++ b/docs/content/en/functions/strings/FirstUpper.md @@ -0,0 +1,19 @@ +--- +title: strings.FirstUpper +description: Returns the given string, capitalizing the first character. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Title + - functions/strings/ToLower + - functions/strings/ToUpper + returnType: string + signatures: [strings.FirstUpper STRING] +aliases: [/functions/strings.firstupper] +--- + +```go-html-template +{{ strings.FirstUpper "foo" }} → Foo +``` diff --git a/docs/content/en/functions/strings/HasPrefix.md b/docs/content/en/functions/strings/HasPrefix.md new file mode 100644 index 000000000..455de0586 --- /dev/null +++ b/docs/content/en/functions/strings/HasPrefix.md @@ -0,0 +1,21 @@ +--- +title: strings.HasPrefix +description: Reports whether the given string begins with the given prefix. +categories: [] +keywords: [] +action: + aliases: [hasPrefix] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasSuffix + - functions/collections/In + returnType: bool + signatures: [strings.HasPrefix STRING PREFIX] +aliases: [/functions/hasprefix,/functions/strings.hasprefix] +--- + +```go-html-template +{{ hasPrefix "Hugo" "Hu" }} → true +``` diff --git a/docs/content/en/functions/strings/HasSuffix.md b/docs/content/en/functions/strings/HasSuffix.md new file mode 100644 index 000000000..8fb12c527 --- /dev/null +++ b/docs/content/en/functions/strings/HasSuffix.md @@ -0,0 +1,21 @@ +--- +title: strings.HasSuffix +description: Reports whether the given string ends with the given suffix. +categories: [] +keywords: [] +action: + aliases: [hasSuffix] + related: + - functions/strings/Contains + - functions/strings/ContainsAny + - functions/strings/ContainsNonSpace + - functions/strings/HasPrefix + - functions/collections/In + returnType: bool + signatures: [strings.HasSuffix STRING SUFFIX] +aliases: [/functions/hassuffix,/functions/strings/hassuffix] +--- + +```go-html-template +{{ hasSuffix "Hugo" "go" }} → true +``` diff --git a/docs/content/en/functions/strings/Repeat.md b/docs/content/en/functions/strings/Repeat.md new file mode 100644 index 000000000..530b0d14b --- /dev/null +++ b/docs/content/en/functions/strings/Repeat.md @@ -0,0 +1,16 @@ +--- +title: strings.Repeat +description: Returns a new string consisting of zero or more copies of another string. +categories: [] +keywords: [] +action: + aliases: [] + related: [] + returnType: string + signatures: [strings.Repeat COUNT INPUT] +aliases: [/functions/strings.repeat] +--- + +```go-html-template +{{ strings.Repeat 3 "yo" }} → yoyoyo +``` diff --git a/docs/content/en/functions/strings/Replace.md b/docs/content/en/functions/strings/Replace.md new file mode 100644 index 000000000..9add6e12b --- /dev/null +++ b/docs/content/en/functions/strings/Replace.md @@ -0,0 +1,26 @@ +--- +title: strings.Replace +description: Returns a copy of INPUT, replacing all occurrences of OLD with NEW. +categories: [] +keywords: [] +action: + aliases: [replace] + related: + - functions/strings/FindRE + - functions/strings/FindRESubmatch + - functions/strings/ReplaceRE + returnType: string + signatures: ['strings.Replace INPUT OLD NEW [LIMIT]'] +aliases: [/functions/replace] +--- + +```go-html-template +{{ $s := "Batman and Robin" }} +{{ replace $s "Robin" "Catwoman" }} → Batman and Catwoman +``` + +Limit the number of replacements using the `LIMIT` argument: + +```go-html-template +{{ replace "aabbaabb" "a" "z" 2 }} → zzbbaabb +``` diff --git a/docs/content/en/functions/strings/ReplaceRE.md b/docs/content/en/functions/strings/ReplaceRE.md new file mode 100644 index 000000000..1c32c34fb --- /dev/null +++ b/docs/content/en/functions/strings/ReplaceRE.md @@ -0,0 +1,43 @@ +--- +title: strings.ReplaceRE +description: Returns a copy of INPUT, replacing all occurrences of a regular expression with a replacement pattern. +categories: [] +keywords: [] +action: + aliases: [replaceRE] + related: + - functions/strings/FindRE + - functions/strings/FindRESubmatch + - functions/strings/Replace + returnType: string + signatures: ['strings.ReplaceRE PATTERN REPLACEMENT INPUT [LIMIT]'] +aliases: [/functions/replacere] +--- + +{{% include "functions/_common/regular-expressions.md" %}} + +```go-html-template +{{ $s := "a-b--c---d" }} +{{ replaceRE `(-{2,})` "-" $s }} → a-b-c-d +``` + +Limit the number of replacements using the LIMIT argument: + +```go-html-template +{{ $s := "a-b--c---d" }} +{{ replaceRE `(-{2,})` "-" $s 1 }} → a-b-c---d +``` + +Use `$1`, `$2`, etc. within the replacement string to insert the content of each capturing group within the regular expression: + +```go-html-template +{{ $s := "http://gohugo.io/docs" }} +{{ replaceRE "^https?://([^/]+).*" "$1" $s }} → gohugo.io +``` + +{{% note %}} +You can write and test your regular expression using [regex101.com](https://regex101.com/). Be sure to select the Go flavor before you begin. +{{% /note %}} + +[RE2]: https://github.com/google/re2/wiki/Syntax +[string literal]: https://go.dev/ref/spec#String_literals diff --git a/docs/content/en/functions/strings/RuneCount.md b/docs/content/en/functions/strings/RuneCount.md new file mode 100644 index 000000000..86aab0c64 --- /dev/null +++ b/docs/content/en/functions/strings/RuneCount.md @@ -0,0 +1,24 @@ +--- +title: strings.RuneCount +description: Returns the number of runes in the given string. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/go-template/len + - functions/strings/Count + - functions/strings/CountRunes + - functions/strings/CountWords + returnType: int + signatures: [strings.RuneCount INPUT] +aliases: [/functions/strings.runecount] +--- + +In contrast with the [`strings.CountRunes`] function, which excludes whitespace, `strings.RuneCount` counts every rune in a string. + +```go-html-template +{{ "Hello, 世界" | strings.RuneCount }} → 9 +``` + +[`strings.CountRunes`]: /functions/strings/countrunes/ diff --git a/docs/content/en/functions/strings/SliceString.md b/docs/content/en/functions/strings/SliceString.md new file mode 100644 index 000000000..ee4ed9081 --- /dev/null +++ b/docs/content/en/functions/strings/SliceString.md @@ -0,0 +1,26 @@ +--- +title: strings.SliceString +description: Returns a substring of the given string, beginning with the start position and ending before the end position. +categories: [] +keywords: [] +action: + aliases: [slicestr] + related: + - functions/strings/Substr + returnType: string + signatures: ['strings.SliceString STRING [START] [END]'] +aliases: [/functions/slicestr] +--- + +The START and END positions are zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. If END is not specified, the substring will end after the last character. + +```go-html-template +{{ slicestr "BatMan" }} → BatMan +{{ slicestr "BatMan" 3 }} → Man +{{ slicestr "BatMan" 0 3 }} → Bat +``` + +The START and END arguments represent the endpoints of a [half-open interval], a concept that may be difficult to grasp when first encountered. You may find that the [`strings.Substr`] function is easier to understand. + +[half-open interval]: /getting-started/glossary/#interval +[`strings.Substr`]: /functions/strings/substr/ diff --git a/docs/content/en/functions/strings/Split.md b/docs/content/en/functions/strings/Split.md new file mode 100644 index 000000000..e3e0ee13e --- /dev/null +++ b/docs/content/en/functions/strings/Split.md @@ -0,0 +1,26 @@ +--- +title: strings.Split +description: Returns a slice of strings by splitting the given string by a delimiter. +categories: [] +keywords: [] +action: + aliases: [split] + related: + - functions/collections/Delimit + returnType: string + signatures: [strings.Split STRING DELIM] +aliases: [/functions/split] +--- + +Examples: + +```go-html-template +{{ split "tag1,tag2,tag3" "," }} → ["tag1", "tag2", "tag3"] +{{ split "abc" "" }} → ["a", "b", "c"] +``` + +{{% note %}} +The `strings.Split` function essentially does the opposite of the [`collections.Delimit`] function. While `split` creates a slice from a string, `delimit` creates a string from a slice. + +[`collections.Delimit`]: /functions/collections/delimit/ +{{% /note %}} diff --git a/docs/content/en/functions/strings/Substr.md b/docs/content/en/functions/strings/Substr.md new file mode 100644 index 000000000..19a029e28 --- /dev/null +++ b/docs/content/en/functions/strings/Substr.md @@ -0,0 +1,37 @@ +--- +title: strings.Substr +description: Returns a substring of the given string, beginning with the start position and ending after the given length. +categories: [] +keywords: [] +action: + aliases: [substr] + related: + - functions/strings/SliceString + returnType: string + signatures: ['strings.Substr STRING [START] [LENGTH]'] +aliases: [/functions/substr] +--- + +The start position is zero-based, where `0` represents the first character of the string. If START is not specified, the substring will begin at position `0`. Specify a negative START position to extract characters from the end of the string. + +If LENGTH is not specified, the substring will include all characters from the START position to the end of the string. If negative, that number of characters will be omitted from the end of string. + +```go-html-template +{{ substr "abcdef" 0 }} → abcdef +{{ substr "abcdef" 1 }} → bcdef + +{{ substr "abcdef" 0 1 }} → a +{{ substr "abcdef" 1 1 }} → b + +{{ substr "abcdef" 0 -1 }} → abcde +{{ substr "abcdef" 1 -1 }} → bcde + +{{ substr "abcdef" -1 }} → f +{{ substr "abcdef" -2 }} → ef + +{{ substr "abcdef" -1 1 }} → f +{{ substr "abcdef" -2 1 }} → e + +{{ substr "abcdef" -3 -1 }} → de +{{ substr "abcdef" -3 -2 }} → d +``` diff --git a/docs/content/en/functions/strings/Title.md b/docs/content/en/functions/strings/Title.md new file mode 100644 index 000000000..b7f1f9e5c --- /dev/null +++ b/docs/content/en/functions/strings/Title.md @@ -0,0 +1,32 @@ +--- +title: strings.Title +description: Returns the given string, converting it to title case. +categories: [] +keywords: [] +action: + aliases: [title] + related: + - functions/strings/FirstUpper + - functions/strings/ToLower + - functions/strings/ToUpper + returnType: string + signatures: [strings.Title STRING] +aliases: [/functions/title] +--- + +```go-html-template +{{ title "table of contents (TOC)" }} → Table of Contents (TOC) +``` + +By default, Hugo follows the capitalization rules published in the [Associated Press Stylebook]. Change your [site configuration] if you would prefer to: + +- Follow the capitalization rules published in the [Chicago Manual of Style] +- Capitalize the first letter of every word +- Capitalize the first letter of the first word +- Disable the effects of the `title` function + +The last option is useful if your theme uses the `title` function, and you would prefer to manually capitalize strings as needed. + +[Associated Press Stylebook]: https://www.apstylebook.com/ +[Chicago Manual of Style]: https://www.chicagomanualofstyle.org/home.html +[site configuration]: /getting-started/configuration/#configure-title-case diff --git a/docs/content/en/functions/strings/ToLower.md b/docs/content/en/functions/strings/ToLower.md new file mode 100644 index 000000000..3da047ae4 --- /dev/null +++ b/docs/content/en/functions/strings/ToLower.md @@ -0,0 +1,19 @@ +--- +title: strings.ToLower +description: Returns the given string, converting all characters to lowercase. +categories: [] +keywords: [] +action: + aliases: [lower] + related: + - functions/strings/FirstUpper + - functions/strings/Title + - functions/strings/ToUpper + returnType: string + signatures: [strings.ToLower INPUT] +aliases: [/functions/lower] +--- + +```go-html-template +{{ lower "BatMan" }} → batman +``` diff --git a/docs/content/en/functions/strings/ToUpper.md b/docs/content/en/functions/strings/ToUpper.md new file mode 100644 index 000000000..617e1e68a --- /dev/null +++ b/docs/content/en/functions/strings/ToUpper.md @@ -0,0 +1,19 @@ +--- +title: strings.ToUpper +description: Returns the given string, converting all characters to uppercase. +categories: [] +keywords: [] +action: + aliases: [upper] + related: + - functions/strings/FirstUpper + - functions/strings/Title + - functions/strings/ToLower + returnType: string + signatures: [strings.ToUpper INPUT] +aliases: [/functions/upper] +--- + +```go-html-template +{{ upper "BatMan" }} → BATMAN +``` diff --git a/docs/content/en/functions/strings/Trim.md b/docs/content/en/functions/strings/Trim.md new file mode 100644 index 000000000..a8c4cf92d --- /dev/null +++ b/docs/content/en/functions/strings/Trim.md @@ -0,0 +1,22 @@ +--- +title: strings.Trim +description: Returns the given string, removing leading and trailing characters specified in the cutset. +categories: [] +keywords: [] +action: + aliases: [trim] + related: + - functions/strings/Chomp + - functions/strings/TrimSpace + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix + returnType: string + signatures: [strings.Trim INPUT CUTSET] +aliases: [/functions/trim] +--- + +```go-html-template +{{ trim "++foo--" "+-" }} → foo +``` diff --git a/docs/content/en/functions/strings/TrimLeft.md b/docs/content/en/functions/strings/TrimLeft.md new file mode 100644 index 000000000..d94aa05a3 --- /dev/null +++ b/docs/content/en/functions/strings/TrimLeft.md @@ -0,0 +1,29 @@ +--- +title: strings.TrimLeft +description: Returns the given string, removing leading characters specified in the cutset. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimSpace + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix + returnType: string + signatures: [strings.TrimLeft CUTSET STRING] +aliases: [/functions/strings.trimleft] +--- + +```go-html-template +{{ strings.TrimLeft "a" "abba" }} → bba +``` + +The `strings.TrimLeft` function converts the arguments to strings if possible: + +```go-html-template +{{ strings.TrimLeft 21 12345 }} → 345 (string) +{{ strings.TrimLeft "rt" true }} → ue +``` diff --git a/docs/content/en/functions/strings/TrimPrefix.md b/docs/content/en/functions/strings/TrimPrefix.md new file mode 100644 index 000000000..331c52a03 --- /dev/null +++ b/docs/content/en/functions/strings/TrimPrefix.md @@ -0,0 +1,24 @@ +--- +title: strings.TrimPrefix +description: Returns the given string, removing the prefix from the beginning of the string. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimSpace + - functions/strings/TrimLeft + - functions/strings/TrimRight + - functions/strings/TrimSuffix + returnType: string + signatures: [strings.TrimPrefix PREFIX STRING] +aliases: [/functions/strings.trimprefix] +--- + +```go-html-template +{{ strings.TrimPrefix "a" "aabbaa" }} → abbaa +{{ strings.TrimPrefix "aa" "aabbaa" }} → bbaa +{{ strings.TrimPrefix "aaa" "aabbaa" }} → aabbaa +``` diff --git a/docs/content/en/functions/strings/TrimRight.md b/docs/content/en/functions/strings/TrimRight.md new file mode 100644 index 000000000..f36597d3d --- /dev/null +++ b/docs/content/en/functions/strings/TrimRight.md @@ -0,0 +1,29 @@ +--- +title: strings.TrimRight +description: Returns the given string, removing trailing characters specified in the cutset. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimSpace + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimSuffix + returnType: string + signatures: [strings.TrimRight CUTSET STRING] +aliases: [/functions/strings.trimright] +--- + +```go-html-template +{{ strings.TrimRight "a" "abba" }} → abb +``` + +The `strings.TrimRight` function converts the arguments to strings if possible: + +```go-html-template +{{ strings.TrimRight 54 12345 }} → 123 (string) +{{ strings.TrimRight "eu" true }} → tr +``` diff --git a/docs/content/en/functions/strings/TrimSpace.md b/docs/content/en/functions/strings/TrimSpace.md new file mode 100644 index 000000000..eef4e8121 --- /dev/null +++ b/docs/content/en/functions/strings/TrimSpace.md @@ -0,0 +1,26 @@ +--- +title: strings.TrimSpace +description: Returns the given string, removing leading and trailing whitespace as defined by Unicode. +categories: [] +keywords: [] +action: + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + - functions/strings/TrimSuffix + returnType: string + signatures: [strings.TrimSpace INPUT] +--- + +{{< new-in 0.136.3 >}} + +Whitespace characters include `\t`, `\n`, `\v`, `\f`, `\r`, and characters in the [Unicode Space Separator] category. + +[Unicode Space Separator]: https://www.compart.com/en/unicode/category/Zs + +```go-html-template +{{ strings.TrimSpace "\n\r\t foo \n\r\t" }} → foo +``` diff --git a/docs/content/en/functions/strings/TrimSuffix.md b/docs/content/en/functions/strings/TrimSuffix.md new file mode 100644 index 000000000..d612ae695 --- /dev/null +++ b/docs/content/en/functions/strings/TrimSuffix.md @@ -0,0 +1,24 @@ +--- +title: strings.TrimSuffix +description: Returns the given string, removing the suffix from the end of the string. +categories: [] +keywords: [] +action: + aliases: [] + related: + - functions/strings/Chomp + - functions/strings/Trim + - functions/strings/TrimSpace + - functions/strings/TrimLeft + - functions/strings/TrimPrefix + - functions/strings/TrimRight + returnType: string + signatures: [strings.TrimSuffix SUFFIX STRING] +aliases: [/functions/strings.trimsuffix] +--- + +```go-html-template +{{ strings.TrimSuffix "a" "aabbaa" }} → aabba +{{ strings.TrimSuffix "aa" "aabbaa" }} → aabb +{{ strings.TrimSuffix "aaa" "aabbaa" }} → aabbaa +``` diff --git a/docs/content/en/functions/strings/Truncate.md b/docs/content/en/functions/strings/Truncate.md new file mode 100644 index 000000000..2e7693eb5 --- /dev/null +++ b/docs/content/en/functions/strings/Truncate.md @@ -0,0 +1,24 @@ +--- +title: strings.Truncate +description: Returns the given string, truncating it to a maximum length without cutting words or leaving unclosed HTML tags. +categories: [] +keywords: [] +action: + aliases: [truncate] + related: [] + returnType: template.HTML + signatures: ['strings.Truncate SIZE [ELLIPSIS] INPUT'] +aliases: [/functions/truncate] +--- + +Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings: + +```go-html-template +{{ "<em>Keep my HTML</em>" | safeHTML | truncate 10 }} → <em>Keep my …</em> +``` + +{{% note %}} +If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML`]function before sending the value to `truncate`. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. + +[`safeHTML`]: /functions/safe/html/ +{{% /note %}} diff --git a/docs/content/en/functions/strings/_index.md b/docs/content/en/functions/strings/_index.md new file mode 100644 index 000000000..364522a3a --- /dev/null +++ b/docs/content/en/functions/strings/_index.md @@ -0,0 +1,12 @@ +--- +title: String functions +linkTitle: strings +description: Template functions to work with strings. +categories: [] +keywords: [] +menu: + docs: + parent: functions +--- + +Use these functions to work with strings. |
