1# String Functions
2
3Sprig has a number of string manipulation functions.
4
5## trim
6
7The `trim` function removes space from either side of a string:
8
9```
10trim " hello "
11```
12
13The above produces `hello`
14
15## trimAll
16
17Remove given characters from the front or back of a string:
18
19```
20trimAll "$" "$5.00"
21```
22
23The above returns `5.00` (as a string).
24
25## trimSuffix
26
27Trim just the suffix from a string:
28
29```
30trimSuffix "-" "hello-"
31```
32
33The above returns `hello`
34
35## trimPrefix
36
37Trim just the prefix from a string:
38
39```
40trimPrefix "-" "-hello"
41```
42
43The above returns `hello`
44
45## upper
46
47Convert the entire string to uppercase:
48
49```
50upper "hello"
51```
52
53The above returns `HELLO`
54
55## lower
56
57Convert the entire string to lowercase:
58
59```
60lower "HELLO"
61```
62
63The above returns `hello`
64
65## title
66
67Convert to title case:
68
69```
70title "hello world"
71```
72
73The above returns `Hello World`
74
75## repeat
76
77Repeat a string multiple times:
78
79```
80repeat 3 "hello"
81```
82
83The above returns `hellohellohello`
84
85## substr
86
87Get a substring from a string. It takes three parameters:
88
89- start (int)
90- end (int)
91- string (string)
92
93```
94substr 0 5 "hello world"
95```
96
97The above returns `hello`
98
99## trunc
100
101Truncate a string (and add no suffix)
102
103```
104trunc 5 "hello world"
105```
106
107The above produces `hello`.
108
109```
110trunc -5 "hello world"
111```
112
113The above produces `world`.
114
115## contains
116
117Test to see if one string is contained inside of another:
118
119```
120contains "cat" "catch"
121```
122
123The above returns `true` because `catch` contains `cat`.
124
125## hasPrefix and hasSuffix
126
127The `hasPrefix` and `hasSuffix` functions test whether a string has a given
128prefix or suffix:
129
130```
131hasPrefix "cat" "catch"
132```
133
134The above returns `true` because `catch` has the prefix `cat`.
135
136## quote and squote
137
138These functions wrap a string in double quotes (`quote`) or single quotes
139(`squote`).
140
141## cat
142
143The `cat` function concatenates multiple strings together into one, separating
144them with spaces:
145
146```
147cat "hello" "beautiful" "world"
148```
149
150The above produces `hello beautiful world`
151
152## indent
153
154The `indent` function indents every line in a given string to the specified
155indent width. This is useful when aligning multi-line strings:
156
157```
158indent 4 $lots_of_text
159```
160
161The above will indent every line of text by 4 space characters.
162
163## nindent
164
165The `nindent` function is the same as the indent function, but prepends a new
166line to the beginning of the string.
167
168```
169nindent 4 $lots_of_text
170```
171
172The above will indent every line of text by 4 space characters and add a new
173line to the beginning.
174
175## replace
176
177Perform simple string replacement.
178
179It takes three arguments:
180
181- string to replace
182- string to replace with
183- source string
184
185```
186"I Am Henry VIII" | replace " " "-"
187```
188
189The above will produce `I-Am-Henry-VIII`
190
191## plural
192
193Pluralize a string.
194
195```
196len $fish | plural "one anchovy" "many anchovies"
197```
198
199In the above, if the length of the string is 1, the first argument will be
200printed (`one anchovy`). Otherwise, the second argument will be printed
201(`many anchovies`).
202
203The arguments are:
204
205- singular string
206- plural string
207- length integer
208
209NOTE: Sprig does not currently support languages with more complex pluralization
210rules. And `0` is considered a plural because the English language treats it
211as such (`zero anchovies`). The Sprig developers are working on a solution for
212better internationalization.
213
214## regexMatch, mustRegexMatch
215
216Returns true if the input string contains any match of the regular expression.
217
218```
219regexMatch "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$" "test@acme.com"
220```
221
222The above produces `true`
223
224`regexMatch` panics if there is a problem and `mustRegexMatch` returns an error to the
225template engine if there is a problem.
226
227## regexFindAll, mustRegexFindAll
228
229Returns a slice of all matches of the regular expression in the input string.
230The last parameter n determines the number of substrings to return, where -1 means return all matches
231
232```
233regexFindAll "[2,4,6,8]" "123456789" -1
234```
235
236The above produces `[2 4 6 8]`
237
238`regexFindAll` panics if there is a problem and `mustRegexFindAll` returns an error to the
239template engine if there is a problem.
240
241## regexFind, mustRegexFind
242
243Return the first (left most) match of the regular expression in the input string
244
245```
246regexFind "[a-zA-Z][1-9]" "abcd1234"
247```
248
249The above produces `d1`
250
251`regexFind` panics if there is a problem and `mustRegexFind` returns an error to the
252template engine if there is a problem.
253
254## regexReplaceAll, mustRegexReplaceAll
255
256Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement.
257Inside string replacement, $ signs are interpreted as in Expand, so for instance $1 represents the text of the first submatch
258
259```
260regexReplaceAll "a(x*)b" "-ab-axxb-" "${1}W"
261```
262
263The above produces `-W-xxW-`
264
265`regexReplaceAll` panics if there is a problem and `mustRegexReplaceAll` returns an error to the
266template engine if there is a problem.
267
268## regexReplaceAllLiteral, mustRegexReplaceAllLiteral
269
270Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement
271The replacement string is substituted directly, without using Expand
272
273```
274regexReplaceAllLiteral "a(x*)b" "-ab-axxb-" "${1}"
275```
276
277The above produces `-${1}-${1}-`
278
279`regexReplaceAllLiteral` panics if there is a problem and `mustRegexReplaceAllLiteral` returns an error to the
280template engine if there is a problem.
281
282## regexSplit, mustRegexSplit
283
284Slices 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
285
286```
287regexSplit "z+" "pizza" -1
288```
289
290The above produces `[pi a]`
291
292`regexSplit` panics if there is a problem and `mustRegexSplit` returns an error to the
293template engine if there is a problem.
294
295## regexQuoteMeta
296
297Returns a string that escapes all regular expression metacharacters inside the argument text;
298the returned string is a regular expression matching the literal text.
299
300```
301regexQuoteMeta "1.2.3"
302```
303
304The above produces `1\.2\.3`
305
306## See Also...
307
308The [Conversion Functions](conversion.html) contain functions for converting
309strings. The [String Slice Functions](string_slice.html) contains functions
310for working with an array of strings.
View as plain text