+
+trim |
+The `trim` function removes space from either side of a string:
```
trim " hello "
```
The above produces `hello`
+ |
+
-## trimAll
-
-Remove given characters from the front or back of a string:
+
+trimAll |
+Remove given characters from the front or back of a string:
```
trimAll "$" "$5.00"
```
The above returns `5.00` (as a string).
+ |
+
-## trimSuffix
-
-Trim just the suffix from a string:
+
+trimSuffix |
+Trim just the suffix from a string:
```
trimSuffix "-" "hello-"
```
The above returns `hello`
+ |
+
-## trimPrefix
-
-Trim just the prefix from a string:
+
+trimPrefix |
+Trim just the prefix from a string:
```
trimPrefix "-" "-hello"
```
The above returns `hello`
+ |
+
-## upper
-
-Convert the entire string to uppercase:
+
+upper |
+Convert the entire string to uppercase:
```
upper "hello"
```
The above returns `HELLO`
+ |
+
-## lower
-
-Convert the entire string to lowercase:
+
+lower |
+Convert the entire string to lowercase:
```
lower "HELLO"
```
The above returns `hello`
+ |
+
-## title
-
-Convert to title case:
+
+title |
+Convert to title case:
```
title "hello world"
```
The above returns `Hello World`
+ |
+
-## repeat
-
-Repeat a string multiple times:
+
+repeat |
+Repeat a string multiple times:
```
repeat 3 "hello"
```
The above returns `hellohellohello`
+ |
+
-## substr
-
-Get a substring from a string. It takes three parameters:
+
+substr |
+Get a substring from a string. It takes three parameters:
- start (int)
- end (int)
@@ -95,10 +133,12 @@ substr 0 5 "hello world"
```
The above returns `hello`
+ |
+
-## trunc
-
-Truncate a string (and add no suffix)
+
+trunc |
+Truncate a string (and add no suffix)
```
trunc 5 "hello world"
@@ -111,20 +151,24 @@ trunc -5 "hello world"
```
The above produces `world`.
+ |
+
-## contains
-
-Test to see if one string is contained inside of another:
+
+contains |
+Test to see if one string is contained inside of another:
```
contains "cat" "catch"
```
The above returns `true` because `catch` contains `cat`.
+ |
+
-## hasPrefix and hasSuffix
-
-The `hasPrefix` and `hasSuffix` functions test whether a string has a given
+
+hasPrefix and hasSuffix |
+The `hasPrefix` and `hasSuffix` functions test whether a string has a given
prefix or suffix:
```
@@ -132,15 +176,19 @@ hasPrefix "cat" "catch"
```
The above returns `true` because `catch` has the prefix `cat`.
+ |
+
-## quote and squote
-
-These functions wrap a string in double quotes (`quote`) or single quotes
+
+quote and squote |
+These functions wrap a string in double quotes (`quote`) or single quotes
(`squote`).
+ |
+
-## cat
-
-The `cat` function concatenates multiple strings together into one, separating
+
+cat |
+The `cat` function concatenates multiple strings together into one, separating
them with spaces:
```
@@ -148,10 +196,12 @@ cat "hello" "beautiful" "world"
```
The above produces `hello beautiful world`
+ |
+
-## indent
-
-The `indent` function indents every line in a given string to the specified
+
+indent |
+The `indent` function indents every line in a given string to the specified
indent width. This is useful when aligning multi-line strings:
```
@@ -159,10 +209,12 @@ indent 4 $lots_of_text
```
The above will indent every line of text by 4 space characters.
+ |
+
-## nindent
-
-The `nindent` function is the same as the indent function, but prepends a new
+
+nindent |
+The `nindent` function is the same as the indent function, but prepends a new
line to the beginning of the string.
```
@@ -171,10 +223,12 @@ nindent 4 $lots_of_text
The above will indent every line of text by 4 space characters and add a new
line to the beginning.
+ |
+
-## replace
-
-Perform simple string replacement.
+
+replace |
+Perform simple string replacement.
It takes three arguments:
@@ -187,10 +241,12 @@ It takes three arguments:
```
The above will produce `I-Am-Henry-VIII`
+ |
+
-## plural
-
-Pluralize a string.
+
+plural |
+Pluralize a string.
```
len $fish | plural "one anchovy" "many anchovies"
@@ -210,10 +266,12 @@ NOTE: Sprig does not currently support languages with more complex pluralization
rules. And `0` is considered a plural because the English language treats it
as such (`zero anchovies`). The Sprig developers are working on a solution for
better internationalization.
+ |
+
-## regexMatch, mustRegexMatch
-
-Returns true if the input string contains any match of the regular expression.
+
+regexMatch, mustRegexMatch |
+Returns true if the input string contains any match of the regular expression.
```
regexMatch "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$" "test@acme.com"
@@ -223,10 +281,12 @@ The above produces `true`
`regexMatch` panics if there is a problem and `mustRegexMatch` returns an error to the
template engine if there is a problem.
+ |
+
-## regexFindAll, mustRegexFindAll
-
-Returns a slice of all matches of the regular expression in the input string.
+
+regexFindAll, mustRegexFindAll |
+Returns a slice of all matches of the regular expression in the input string.
The last parameter n determines the number of substrings to return, where -1 means return all matches
```
@@ -237,10 +297,12 @@ The above produces `[2 4 6 8]`
`regexFindAll` panics if there is a problem and `mustRegexFindAll` returns an error to the
template engine if there is a problem.
+ |
+
-## regexFind, mustRegexFind
-
-Return the first (left most) match of the regular expression in the input string
+
+regexFind, mustRegexFind |
+Return the first (left most) match of the regular expression in the input string
```
regexFind "[a-zA-Z][1-9]" "abcd1234"
@@ -250,10 +312,12 @@ The above produces `d1`
`regexFind` panics if there is a problem and `mustRegexFind` returns an error to the
template engine if there is a problem.
+ |
+
-## regexReplaceAll, mustRegexReplaceAll
-
-Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement.
+
+regexReplaceAll, mustRegexReplaceAll |
+Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement.
Inside string replacement, $ signs are interpreted as in Expand, so for instance $1 represents the text of the first submatch
```
@@ -264,10 +328,12 @@ The above produces `-W-xxW-`
`regexReplaceAll` panics if there is a problem and `mustRegexReplaceAll` returns an error to the
template engine if there is a problem.
+ |
+
-## regexReplaceAllLiteral, mustRegexReplaceAllLiteral
-
-Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement
+
+regexReplaceAllLiteral, mustRegexReplaceAllLiteral |
+Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement
The replacement string is substituted directly, without using Expand
```
@@ -278,10 +344,12 @@ The above produces `-${1}-${1}-`
`regexReplaceAllLiteral` panics if there is a problem and `mustRegexReplaceAllLiteral` returns an error to the
template engine if there is a problem.
+ |
+
-## regexSplit, mustRegexSplit
-
-Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. The last parameter `n` determines the number of substrings to return, where `-1` means return all matches
+
+regexSplit, mustRegexSplit |
+Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. The last parameter `n` determines the number of substrings to return, where `-1` means return all matches
```
regexSplit "z+" "pizza" -1
@@ -291,10 +359,12 @@ The above produces `[pi a]`
`regexSplit` panics if there is a problem and `mustRegexSplit` returns an error to the
template engine if there is a problem.
+ |
+
-## regexQuoteMeta
-
-Returns a string that escapes all regular expression metacharacters inside the argument text;
+
+regexQuoteMeta |
+Returns a string that escapes all regular expression metacharacters inside the argument text;
the returned string is a regular expression matching the literal text.
```
@@ -302,19 +372,22 @@ regexQuoteMeta "1.2.3"
```
The above produces `1\.2\.3`
-
-## See Also...
+ |
+
+
The [Conversion Functions](conversion.md) contain functions for converting strings. The [String List Functions](string_slice.md) contains
functions for working with an array of strings.
-# String List Functions
+
+## String List Functions
These function operate on or generate slices of strings. In Go, a slice is a
growable array. In Sprig, it's a special case of a `list`.
-## join
-
-Join a list of strings into a single string, with the given separator.
+
+
+add |
+Sum numbers with `add`. Accepts two or more inputs.
```
add 1 2 3
```
+ |
+
-## add1
+
+add1 |
+To increment by 1, use `add1`
+ |
+
-To increment by 1, use `add1`
+
+sub |
+To subtract, use `sub`
+ |
+
-## sub
+
+div |
+Perform integer division with `div`
+ |
+
-To subtract, use `sub`
+
+mod |
+Modulo with `mod`
+ |
+
-## div
-
-Perform integer division with `div`
-
-## mod
-
-Modulo with `mod`
-
-## mul
-
-Multiply with `mul`. Accepts two or more inputs.
+
+mul |
+Multiply with `mul`. Accepts two or more inputs.
```
mul 1 2 3
```
+ |
+
-## max
-
-Return the largest of a series of integers:
+
+max |
+Return the largest of a series of integers:
This will return `3`:
```
max 1 2 3
```
+ |
+
-## min
-
-Return the smallest of a series of integers.
+
+min |
+Return the smallest of a series of integers.
`min 1 2 3` will return `1`
+ |
+
-## floor
-
-Returns the greatest float value less than or equal to input value
+
+floor |
+Returns the greatest float value less than or equal to input value
`floor 123.9999` will return `123.0`
+ |
+
-## ceil
-
-Returns the greatest float value greater than or equal to input value
+
+ceil |
+Returns the greatest float value greater than or equal to input value
`ceil 123.001` will return `124.0`
+ |
+
-## round
-
-Returns a float value with the remainder rounded to the given number to digits after the decimal point.
+
+round |
+Returns a float value with the remainder rounded to the given number to digits after the decimal point.
`round 123.555555 3` will return `123.556`
+ |
+
-## randInt
-Returns a random integer value from min (inclusive) to max (exclusive).
+
+randInt |
+Returns a random integer value from min (inclusive) to max (exclusive).
```
randInt 12 30
```
The above will produce a random number in the range [12,30].
-# Integer List Functions
+ |
+
+
-## until
+## Integer List Functions
-The `until` function builds a range of integers.
+
+
+until |
+The `until` function builds a range of integers.
```
until 5
@@ -470,10 +582,12 @@ until 5
The above generates the list `[0, 1, 2, 3, 4]`.
This is useful for looping with `range $i, $e := until 5`.
+ |
+
-## untilStep
-
-Like `until`, `untilStep` generates a list of counting integers. But it allows
+
+untilStep |
+Like `until`, `untilStep` generates a list of counting integers. But it allows
you to define a start, stop, and step:
```
@@ -482,10 +596,12 @@ untilStep 3 6 2
The above will produce `[3 5]` by starting with 3, and adding 2 until it is equal
or greater than 6. This is similar to Python's `range` function.
+ |
+
-## seq
-
-Works like the bash `seq` command.
+
+seq |
+Works like the bash `seq` command.
* 1 parameter (end) - will generate all counting integers between 1 and `end` inclusive.
* 2 parameters (start, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by 1.
* 3 parameters (start, step, end) - will generate all counting integers between `start` and `end` inclusive incrementing or decrementing by `step`.
@@ -498,15 +614,22 @@ seq 2 -2 => 2 1 0 -1 -2
seq 0 2 10 => 0 2 4 6 8 10
seq 0 -2 -5 => 0 -2 -4
```
-# Date Functions
+ |
+
+
-## now
+## Date Functions
-The current date/time. Use this in conjunction with other date functions.
+
+
+now |
+The current date/time. Use this in conjunction with other date functions.
+ |
+
-## ago
-
-The `ago` function returns duration from time.Now in seconds resolution.
+
+ago |
+The `ago` function returns duration from time.Now in seconds resolution.
```
ago .CreatedAt
@@ -517,10 +640,12 @@ returns in `time.Duration` String() format
```
2h34m7s
```
+ |
+
-## date
-
-The `date` function formats a date.
+
+date |
+The `date` function formats a date.
Format the date to YEAR-MONTH-DAY:
@@ -538,28 +663,34 @@ Mon Jan 2 15:04:05 MST 2006
Write it in the format you want. Above, `2006-01-02` is the same date, but
in the format we want.
+ |
+
-## dateInZone
-
-Same as `date`, but with a timezone.
+
+dateInZone |
+Same as `date`, but with a timezone.
```
dateInZone "2006-01-02" (now) "UTC"
```
+ |
+
-## duration
-
-Formats a given amount of seconds as a `time.Duration`.
+
+duration |
+Formats a given amount of seconds as a `time.Duration`.
This returns 1m35s
```
duration "95"
```
+ |
+
-## durationRound
-
-Rounds a given duration to the most significant unit. Strings and `time.Duration`
+
+durationRound |
+Rounds a given duration to the most significant unit. Strings and `time.Duration`
gets parsed as a duration, while a `time.Time` is calculated as the duration since.
This return 2h
@@ -573,18 +704,22 @@ This returns 3mo
```
durationRound "2400h10m5s"
```
+ |
+
-## unixEpoch
-
-Returns the seconds since the unix epoch for a `time.Time`.
+
+unixEpoch |
+Returns the seconds since the unix epoch for a `time.Time`.
```
now | unixEpoch
```
+ |
+
-## dateModify, mustDateModify
-
-The `dateModify` takes a modification and a date and returns the timestamp.
+
+dateModify, mustDateModify |
+The `dateModify` takes a modification and a date and returns the timestamp.
Subtract an hour and thirty minutes from the current time:
@@ -593,27 +728,33 @@ now | date_modify "-1.5h"
```
If the modification format is wrong `dateModify` will return the date unmodified. `mustDateModify` will return an error otherwise.
+ |
+
-## htmlDate
-
-The `htmlDate` function formats a date for inserting into an HTML date picker
+
+htmlDate |
+The `htmlDate` function formats a date for inserting into an HTML date picker
input field.
```
now | htmlDate
```
+ |
+
-## htmlDateInZone
-
-Same as htmlDate, but with a timezone.
+
+htmlDateInZone |
+Same as htmlDate, but with a timezone.
```
htmlDateInZone (now) "UTC"
```
+ |
+
-## toDate, mustToDate
-
-`toDate` converts a string to a date. The first argument is the date layout and
+
+toDate, mustToDate |
+`toDate` converts a string to a date. The first argument is the date layout and
the second the date string. If the string can't be convert it returns the zero
value.
`mustToDate` will return an error in case the string cannot be converted.
@@ -624,13 +765,18 @@ This is useful when you want to convert a string date to another format
```
toDate "2006-01-02" "2017-12-31" | date "02/01/2006"
```
-# Default Functions
+ |
+
+
+
+## Default Functions
Sprig provides tools for setting default values for templates.
-## default
-
-To set a simple default value, use `default`:
+
+
+default |
+To set a simple default value, use `default`:
```
default "foo" .Bar
@@ -650,10 +796,12 @@ The definition of "empty" depends on type:
For structs, there is no definition of empty, so a struct will never return the
default.
+ |
+
-## empty
-
-The `empty` function returns `true` if the given value is considered empty, and
+
+empty |
+The `empty` function returns `true` if the given value is considered empty, and
`false` otherwise. The empty values are listed in the `default` section.
```
@@ -662,10 +810,12 @@ empty .Foo
Note that in Go template conditionals, emptiness is calculated for you. Thus,
you rarely need `if empty .Foo`. Instead, just use `if .Foo`.
+ |
+
-## coalesce
-
-The `coalesce` function takes a list of values and returns the first non-empty
+
+coalesce |
+The `coalesce` function takes a list of values and returns the first non-empty
one.
```
@@ -683,10 +833,12 @@ coalesce .name .parent.name "Matt"
The above will first check to see if `.name` is empty. If it is not, it will return
that value. If it _is_ empty, `coalesce` will evaluate `.parent.name` for emptiness.
Finally, if both `.name` and `.parent.name` are empty, it will return `Matt`.
+ |
+
-## all
-
-The `all` function takes a list of values and returns true if all values are non-empty.
+
+all |
+The `all` function takes a list of values and returns true if all values are non-empty.
```
all 0 1 2
@@ -701,10 +853,12 @@ all (eq .Request.TLS.Version 0x0304) (.Request.ProtoAtLeast 2 0) (eq .Request.Me
```
The above will check http.Request is POST with tls 1.3 and http/2.
+ |
+
-## any
-
-The `any` function takes a list of values and returns true if any value is non-empty.
+
+any |
+The `any` function takes a list of values and returns true if any value is non-empty.
```
any 0 1 2
@@ -719,19 +873,23 @@ any (eq .Request.Method "GET") (eq .Request.Method "POST") (eq .Request.Method "
```
The above will check http.Request method is one of GET/POST/OPTIONS.
+ |
+
-## fromJSON, mustFromJSON
-
-`fromJSON` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string.
+
+fromJSON, mustFromJSON |
+`fromJSON` decodes a JSON document into a structure. If the input cannot be decoded as JSON the function will return an empty string.
`mustFromJSON` will return an error in case the JSON is invalid.
```
fromJSON "{\"foo\": 55}"
```
+ |
+
-## toJSON, mustToJSON
-
-The `toJSON` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string.
+
+toJSON, mustToJSON |
+The `toJSON` function encodes an item into a JSON string. If the item cannot be converted to JSON the function will return an empty string.
`mustToJSON` will return an error in case the item cannot be encoded in JSON.
```
@@ -739,30 +897,36 @@ toJSON .Item
```
The above returns JSON string representation of `.Item`.
+ |
+
-## toPrettyJSON, mustToPrettyJSON
-
-The `toPrettyJSON` function encodes an item into a pretty (indented) JSON string.
+
+toPrettyJSON, mustToPrettyJSON |
+The `toPrettyJSON` function encodes an item into a pretty (indented) JSON string.
```
toPrettyJSON .Item
```
The above returns indented JSON string representation of `.Item`.
+ |
+
-## toRawJSON, mustToRawJSON
-
-The `toRawJSON` function encodes an item into JSON string with HTML characters unescaped.
+
+toRawJSON, mustToRawJSON |
+The `toRawJSON` function encodes an item into JSON string with HTML characters unescaped.
```
toRawJSON .Item
```
The above returns unescaped JSON string representation of `.Item`.
+ |
+
-## ternary
-
-The `ternary` function takes two values, and a test value. If the test value is
+
+ternary |
+The `ternary` function takes two values, and a test value. If the test value is
true, the first value will be returned. If the test value is empty, the second
value will be returned. This is similar to the c ternary operator.
@@ -793,13 +957,29 @@ false | ternary "foo" "bar"
```
The above returns `"bar"`.
-# Encoding Functions
+ |
+
+
+
+## Encoding Functions
Sprig has the following encoding and decoding functions:
-- `b64enc`/`b64dec`: Encode or decode with Base64
-- `b32enc`/`b32dec`: Encode or decode with Base32
-# Lists and List Functions
+
+
+first, mustFirst |
+To get the head item on a list, use `first`.
`first $myList` returns `1`
`first` panics if there is a problem while `mustFirst` returns an error to the
template engine if there is a problem.
+ |
+
-## rest, mustRest
-
-To get the tail of the list (everything but the first item), use `rest`.
+
+rest, mustRest |
+To get the tail of the list (everything but the first item), use `rest`.
`rest $myList` returns `[2 3 4 5]`
`rest` panics if there is a problem while `mustRest` returns an error to the
template engine if there is a problem.
+ |
+
-## last, mustLast
-
-To get the last item on a list, use `last`:
+
+last, mustLast |
+To get the last item on a list, use `last`:
`last $myList` returns `5`. This is roughly analogous to reversing a list and
then calling `first`.
`last` panics if there is a problem while `mustLast` returns an error to the
template engine if there is a problem.
+ |
+
-## initial, mustInitial
-
-This compliments `last` by returning all _but_ the last element.
+
+initial, mustInitial |
+This compliments `last` by returning all _but_ the last element.
`initial $myList` returns `[1 2 3 4]`.
`initial` panics if there is a problem while `mustInitial` returns an error to the
template engine if there is a problem.
+ |
+
-## append, mustAppend
-
-Append a new item to an existing list, creating a new list.
+
+append, mustAppend |
+Append a new item to an existing list, creating a new list.
```
$new = append $myList 6
@@ -861,10 +1050,12 @@ The above would set `$new` to `[1 2 3 4 5 6]`. `$myList` would remain unaltered.
`append` panics if there is a problem while `mustAppend` returns an error to the
template engine if there is a problem.
+ |
+
-## prepend, mustPrepend
-
-Push an element onto the front of a list, creating a new list.
+
+prepend, mustPrepend |
+Push an element onto the front of a list, creating a new list.
```
prepend $myList 0
@@ -874,20 +1065,24 @@ The above would produce `[0 1 2 3 4 5]`. `$myList` would remain unaltered.
`prepend` panics if there is a problem while `mustPrepend` returns an error to the
template engine if there is a problem.
+ |
+
-## concat
-
-Concatenate arbitrary number of lists into one.
+
+concat |
+Concatenate arbitrary number of lists into one.
```
concat $myList ( list 6 7 ) ( list 8 )
```
The above would produce `[1 2 3 4 5 6 7 8]`. `$myList` would remain unaltered.
+ |
+
-## reverse, mustReverse
-
-Produce a new list with the reversed elements of the given list.
+
+reverse, mustReverse |
+Produce a new list with the reversed elements of the given list.
```
reverse $myList
@@ -897,10 +1092,12 @@ The above would generate the list `[5 4 3 2 1]`.
`reverse` panics if there is a problem while `mustReverse` returns an error to the
template engine if there is a problem.
+ |
+
-## uniq, mustUniq
-
-Generate a list with all of the duplicates removed.
+
+uniq, mustUniq |
+Generate a list with all of the duplicates removed.
```
list 1 1 1 2 | uniq
@@ -910,10 +1107,12 @@ The above would produce `[1 2]`
`uniq` panics if there is a problem while `mustUniq` returns an error to the
template engine if there is a problem.
+ |
+
-## without, mustWithout
-
-The `without` function filters items out of a list.
+
+without, mustWithout |
+The `without` function filters items out of a list.
```
without $myList 3
@@ -931,10 +1130,12 @@ That would produce `[2 4]`
`without` panics if there is a problem while `mustWithout` returns an error to the
template engine if there is a problem.
+ |
+
-## has, mustHas
-
-Test to see if a list has a particular element.
+
+has, mustHas |
+Test to see if a list has a particular element.
```
has 4 $myList
@@ -944,10 +1145,12 @@ The above would return `true`, while `has "hello" $myList` would return false.
`has` panics if there is a problem while `mustHas` returns an error to the
template engine if there is a problem.
+ |
+
-## compact, mustCompact
-
-Accepts a list and removes entries with empty values.
+
+compact, mustCompact |
+Accepts a list and removes entries with empty values.
```
$list := list 1 "a" "foo" ""
@@ -958,10 +1161,12 @@ $copy := compact $list
`compact` panics if there is a problem and `mustCompact` returns an error to the
template engine if there is a problem.
+ |
+
-## slice, mustSlice
-
-To get partial elements of a list, use `slice list [n] [m]`. It is
+
+slice, mustSlice |
+To get partial elements of a list, use `slice list [n] [m]`. It is
equivalent of `list[n:m]`.
- `slice $myList` returns `[1 2 3 4 5]`. It is same as `myList[:]`.
@@ -971,23 +1176,29 @@ equivalent of `list[n:m]`.
`slice` panics if there is a problem while `mustSlice` returns an error to the
template engine if there is a problem.
+ |
+
-## chunk
-
-To split a list into chunks of given size, use `chunk size list`. This is useful for pagination.
+
+chunk |
+To split a list into chunks of given size, use `chunk size list`. This is useful for pagination.
```
chunk 3 (list 1 2 3 4 5 6 7 8)
```
This produces list of lists `[ [ 1 2 3 ] [ 4 5 6 ] [ 7 8 ] ]`.
+ |
+
+
-## A Note on List Internals
+### A Note on List Internals
A list is implemented in Go as a `[]interface{}`. For Go developers embedding
Sprig, you may pass `[]interface{}` items into your template context and be
able to use all of the `list` functions on those items.
-# Dictionaries and Dict Functions
+
+## Dictionaries and Dict Functions
Sprig provides a key/value storage type called a `dict` (short for "dictionary",
as in Python). A `dict` is an _unorder_ type.
@@ -998,9 +1209,10 @@ type, even another `dict` or `list`.
Unlike `list`s, `dict`s are not immutable. The `set` and `unset` functions will
modify the contents of a dictionary.
-## dict
-
-Creating dictionaries is done by calling the `dict` function and passing it a
+
+
+dict |
+Creating dictionaries is done by calling the `dict` function and passing it a
list of pairs.
The following creates a dictionary with three items:
@@ -1008,10 +1220,12 @@ The following creates a dictionary with three items:
```
$myDict := dict "name1" "value1" "name2" "value2" "name3" "value 3"
```
+ |
+
-## get
-
-Given a map and a key, get the value from the map.
+
+get |
+Given a map and a key, get the value from the map.
```
get $myDict "name1"
@@ -1021,10 +1235,12 @@ The above returns `"value1"`
Note that if the key is not found, this operation will simply return `""`. No error
will be generated.
+ |
+
-## set
-
-Use `set` to add a new key/value pair to a dictionary.
+
+set |
+Use `set` to add a new key/value pair to a dictionary.
```
$_ := set $myDict "name4" "value4"
@@ -1032,10 +1248,12 @@ $_ := set $myDict "name4" "value4"
Note that `set` _returns the dictionary_ (a requirement of Go template functions),
so you may need to trap the value as done above with the `$_` assignment.
+ |
+
-## unset
-
-Given a map and a key, delete the key from the map.
+
+unset |
+Given a map and a key, delete the key from the map.
```
$_ := unset $myDict "name4"
@@ -1045,20 +1263,24 @@ As with `set`, this returns the dictionary.
Note that if the key is not found, this operation will simply return. No error
will be generated.
+ |
+
-## hasKey
-
-The `hasKey` function returns `true` if the given dict contains the given key.
+
+hasKey |
+The `hasKey` function returns `true` if the given dict contains the given key.
```
hasKey $myDict "name1"
```
If the key is not found, this returns `false`.
+ |
+
-## pluck
-
-The `pluck` function makes it possible to give one key and multiple maps, and
+
+pluck |
+The `pluck` function makes it possible to give one key and multiple maps, and
get a list of all of the matches:
```
@@ -1076,10 +1298,12 @@ inserted.
A common idiom in Sprig templates is to uses `pluck... | first` to get the first
matching key out of a collection of dictionaries.
+ |
+
-## dig
-
-The `dig` function traverses a nested set of dicts, selecting keys from a list
+
+dig |
+The `dig` function traverses a nested set of dicts, selecting keys from a list
of values. It returns a default value if any of the keys are not found at the
associated dict.
@@ -1107,10 +1331,12 @@ especially since Go's template package's `and` doesn't shortcut. For instance
`a.maybeNil.iNeedThis`, and panic if `a` lacks a `maybeNil` field.)
`dig` accepts its dict argument last in order to support pipelining.
+ |
+
-## keys
-
-The `keys` function will return a `list` of all of the keys in one or more `dict`
+
+keys |
+The `keys` function will return a `list` of all of the keys in one or more `dict`
types. Since a dictionary is _unordered_, the keys will not be in a predictable order.
They can be sorted with `sortAlpha`.
@@ -1124,10 +1350,12 @@ function along with `sortAlpha` to get a unqiue, sorted list of keys.
```
keys $myDict $myOtherDict | uniq | sortAlpha
```
+ |
+
-## pick
-
-The `pick` function selects just the given keys out of a dictionary, creating a
+
+pick |
+The `pick` function selects just the given keys out of a dictionary, creating a
new `dict`.
```
@@ -1135,10 +1363,12 @@ $new := pick $myDict "name1" "name2"
```
The above returns `{name1: value1, name2: value2}`
+ |
+
-## omit
-
-The `omit` function is similar to `pick`, except it returns a new `dict` with all
+
+omit |
+The `omit` function is similar to `pick`, except it returns a new `dict` with all
the keys that _do not_ match the given keys.
```
@@ -1146,10 +1376,12 @@ $new := omit $myDict "name1" "name3"
```
The above returns `{name2: value2}`
+ |
+
-## values
-
-The `values` function is similar to `keys`, except it returns a new `list` with
+
+values |
+The `values` function is similar to `keys`, except it returns a new `list` with
all the values of the source `dict` (only one dictionary is supported).
```
@@ -1159,48 +1391,68 @@ $vals := values $myDict
The above returns `list["value1", "value2", "value 3"]`. Note that the `values`
function gives no guarantees about the result ordering- if you care about this,
then use `sortAlpha`.
-# Type Conversion Functions
+ |
+
+
+
+## Type Conversion Functions
The following type conversion functions are provided by Sprig:
-- `atoi`: Convert a string to an integer.
-- `float64`: Convert to a `float64`.
-- `int`: Convert to an `int` at the system's width.
-- `int64`: Convert to an `int64`.
-- `toDecimal`: Convert a unix octal to a `int64`.
-- `toString`: Convert to a string.
-- `toStrings`: Convert a list, slice, or array to a list of strings.
+