String functions

String functions available through the builtin object string.

• string.escape
• string.append
• string.capitalize
• string.capitalizewords
• string.contains
• string.empty
• string.whitespace
• string.downcase
• string.ends_with
• string.equals_ignore_case
• string.handleize
• string.literal
• string.lstrip
• string.pluralize
• string.prepend
• string.remove
• string.remove_first
• string.remove_last
• string.replace
• string.replace_first
• string.rstrip
• string.size
• string.slice
• string.slice1
• string.split
• string.starts_with
• string.strip
• string.strip_newlines
• string.to_int
• string.to_long
• string.to_float
• string.to_double
• string.truncate
• string.truncatewords
• string.upcase
• string5
• string.sha1
• string.sha256
• string.sha512
• string.hmac_sha1
• string.hmac_sha256
• string.hmac_sha512
• string.pad_left
• string.pad_right
• string.base64_encode
• string.base64_decode
• string.index_of

string.escapeCopy Anchor Link

string.escape <text>

DescriptionCopy Anchor Link

Escapes a string with escape characters.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The two strings concatenated

ExamplesCopy Anchor Link

input

{{ "Hel\tlo\n\"W\\orld" | string.escape }}

output

Hel\tlo\n\"W\\orld

string.appendCopy Anchor Link

string.append <text> <with>

DescriptionCopy Anchor Link

Concatenates two strings

ArgumentsCopy Anchor Link

• text: The input string
• with: The text to append

ReturnsCopy Anchor Link

The two strings concatenated

ExamplesCopy Anchor Link

input

{{ "Hello" | string.append " World" }}

output

Hello World

string.capitalizeCopy Anchor Link

string.capitalize <text>

DescriptionCopy Anchor Link

Converts the first character of the passed string to a upper case character.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The capitalized input string

ExamplesCopy Anchor Link

input

{{ "test" | string.capitalize }}

output

Test

string.capitalizewordsCopy Anchor Link

string.capitalizewords <text>

DescriptionCopy Anchor Link

Converts the first character of each word in the passed string to a upper case character.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The capitalized input string

ExamplesCopy Anchor Link

input

{{ "This is easy" | string.capitalizewords }}

output

This Is Easy

string.containsCopy Anchor Link

string.contains <text> <value>

DescriptionCopy Anchor Link

Returns a boolean indicating whether the input string contains the specified string value.

ArgumentsCopy Anchor Link

• text: The input string
• value: The string to look for

ReturnsCopy Anchor Link

if text contains the string value

ExamplesCopy Anchor Link

input

{{ "This is easy" | string.contains "easy" }}

output

true

string.emptyCopy Anchor Link

string.empty <text>

DescriptionCopy Anchor Link

Returns a boolean indicating whether the input string is an empty string.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

if text is an empty string

ExamplesCopy Anchor Link

input

{{ "" | string.empty }}

output

true

string.whitespaceCopy Anchor Link

string.whitespace <text>

DescriptionCopy Anchor Link

Returns a boolean indicating whether the input string is empty or contains only whitespace characters.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

if text is empty string or contains only whitespace characters

ExamplesCopy Anchor Link

input

{{ "" | string.whitespace }}

output

true

string.downcaseCopy Anchor Link

string.downcase <text>

DescriptionCopy Anchor Link

Converts the string to lower case.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The input string lower case

ExamplesCopy Anchor Link

input

{{ "TeSt" | string.downcase }}

output

test

string.ends_withCopy Anchor Link

string.ends_with <text> <value>

DescriptionCopy Anchor Link

Returns a boolean indicating whether the input string ends with the specified string value.

ArgumentsCopy Anchor Link

• text: The input string
• value: The string to look for

ReturnsCopy Anchor Link

if text ends with the specified string value

ExamplesCopy Anchor Link

input

{{ "This is easy" | string.ends_with "easy" }}

output

true

string.equals_ignore_caseCopy Anchor Link

string.equals_ignore_case <text> <value>

DescriptionCopy Anchor Link

Returns a boolean indicating whether the input string is equal to specified string 'value'. Comparison is case insensitive.

ArgumentsCopy Anchor Link

• text: The input string
• value: The string to compare

ReturnsCopy Anchor Link

if text is equal to string value, ignoring case

ExamplesCopy Anchor Link

input

{{ "Scriban" | string.equals_ignore_case "SCRIBAN" }}

output

true

string.handleizeCopy Anchor Link

string.handleize <text>

DescriptionCopy Anchor Link

Returns a url handle from the input string.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

A url handle

ExamplesCopy Anchor Link

input

{{ '100% M & Ms!!!' | string.handleize  }}

output

100-m-ms

string.literalCopy Anchor Link

string.literal <text>

DescriptionCopy Anchor Link

Return a string literal enclosed with double quotes of the input string.

ArgumentsCopy Anchor Link

• text: The string to return a literal from.

ReturnsCopy Anchor Link

The literal of a string.

ExamplesCopy Anchor Link

If the input string has non printable characters or they need contain a double quote, they will be escaped.

input

{{ 'Hello\n"World"' | string.literal }}

output

"Hello\n\"World\""

string.lstripCopy Anchor Link

string.lstrip <text>

DescriptionCopy Anchor Link

Removes any whitespace characters on the left side of the input string.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The input string without any left whitespace characters

ExamplesCopy Anchor Link

input

{{ '   too many spaces' | string.lstrip  }}

Highlight to see the empty spaces to the right of the string output

too many spaces

string.pluralizeCopy Anchor Link

string.pluralize <number> <singular> <plural>

DescriptionCopy Anchor Link

Outputs the singular or plural version of a string based on the value of a number.

ArgumentsCopy Anchor Link

• number: The number to check
• singular: The singular string to return if number is == 1
• plural: The plural string to return if number is != 1

ReturnsCopy Anchor Link

The singular or plural string based on number

ExamplesCopy Anchor Link

input

{{ products.size }} {{products.size | string.pluralize 'product' 'products' }}

output

7 products

string.prependCopy Anchor Link

string.prepend <text> <by>

DescriptionCopy Anchor Link

Concatenates two strings by placing the by string in from of the text string

ArgumentsCopy Anchor Link

• text: The input string
• by: The string to prepend to text

ReturnsCopy Anchor Link

The two strings concatenated

ExamplesCopy Anchor Link

input

{{ "World" | string.prepend "Hello " }}

output

Hello World

string.removeCopy Anchor Link

string.remove <text> <remove>

DescriptionCopy Anchor Link

Removes all occurrences of a substring from a string.

ArgumentsCopy Anchor Link

• text: The input string
• remove: The substring to remove from the text string

ReturnsCopy Anchor Link

The input string with the all occurence of a substring removed

ExamplesCopy Anchor Link

input

{{ "Hello, world. Goodbye, world." | string.remove "world" }}

output

Hello, . Goodbye, .

string.remove_firstCopy Anchor Link

string.remove_first <text> <remove>

DescriptionCopy Anchor Link

Removes the first occurrence of a substring from a string.

ArgumentsCopy Anchor Link

• text: The input string
• remove: The first occurence of substring to remove from the text string

ReturnsCopy Anchor Link

The input string with the first occurence of a substring removed

ExamplesCopy Anchor Link

input

{{ "Hello, world. Goodbye, world." | string.remove_first "world" }}

output

Hello, . Goodbye, world.

string.remove_lastCopy Anchor Link

string.remove_last <text> <remove>

DescriptionCopy Anchor Link

Removes the last occurrence of a substring from a string.

ArgumentsCopy Anchor Link

• text: The input string
• remove: The last occurence of substring to remove from the text string

ReturnsCopy Anchor Link

The input string with the first occurence of a substring removed

ExamplesCopy Anchor Link

input

{{ "Hello, world. Goodbye, world." | string.remove_last "world" }}

output

Hello, world. Goodbye, .

string.replaceCopy Anchor Link

string.replace <text> <match> <replace>

DescriptionCopy Anchor Link

Replaces all occurrences of a string with a substring.

ArgumentsCopy Anchor Link

• text: The input string
• match: The substring to find in the text string
• replace: The substring used to replace the string matched by match in the input text

ReturnsCopy Anchor Link

The input string replaced

ExamplesCopy Anchor Link

input

{{ "Hello, world. Goodbye, world." | string.replace "world" "buddy" }}

output

Hello, buddy. Goodbye, buddy.

string.replace_firstCopy Anchor Link

string.replace_first <text> <match> <replace> <fromEnd: False>?

DescriptionCopy Anchor Link

Replaces the first occurrence of a string with a substring.

ArgumentsCopy Anchor Link

• text: The input string
• match: The substring to find in the text string
• replace: The substring used to replace the string matched by match in the input text
• fromEnd: if true start match from end

ReturnsCopy Anchor Link

The input string replaced

ExamplesCopy Anchor Link

input

{{ "Hello, world. Goodbye, world." | string.replace_first "world" "buddy" }}

output

Hello, buddy. Goodbye, world.

string.rstripCopy Anchor Link

string.rstrip <text>

DescriptionCopy Anchor Link

Removes any whitespace characters on the right side of the input string.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The input string without any left whitespace characters

ExamplesCopy Anchor Link

input

{{ '   too many spaces           ' | string.rstrip  }}

Highlight to see the empty spaces to the right of the string output

too many spaces

string.sizeCopy Anchor Link

string.size <text>

DescriptionCopy Anchor Link

Returns the number of characters from the input string

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The length of the input string

ExamplesCopy Anchor Link

input

{{ "test" | string.size }}

output

4

string.sliceCopy Anchor Link

string.slice <text> <start> <length>?

DescriptionCopy Anchor Link

The slice returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring with the remaining characters will be returned.

ArgumentsCopy Anchor Link

• text: The input string
• start: The starting index character where the slice should start from the input text string
• length: The number of character. Default is 0, meaning that the remaining of the string will be returned.

ReturnsCopy Anchor Link

The input string sliced

ExamplesCopy Anchor Link

input

{{ "hello" | string.slice 0 }}
{{ "hello" | string.slice 1 }}
{{ "hello" | string.slice 1 3 }}
{{ "hello" | string.slice 1 length:3 }}

output

hello ello ell ell

string.slice1Copy Anchor Link

string.slice1 <text> <start> <length: 1>?

DescriptionCopy Anchor Link

The slice returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring with the first character will be returned.

ArgumentsCopy Anchor Link

• text: The input string
• start: The starting index character where the slice should start from the input text string
• length: The number of character. Default is 1, meaning that only the first character at start position will be returned.

ReturnsCopy Anchor Link

The input string sliced

ExamplesCopy Anchor Link

input

{{ "hello" | string.slice1 0 }}
{{ "hello" | string.slice1 1 }}
{{ "hello" | string.slice1 1 3 }}
{{ "hello" | string.slice1 1 length: 3 }}

output

h e ell ell

string.splitCopy Anchor Link

string.split <text> <match>

DescriptionCopy Anchor Link

The split function takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. You can output different parts of an array using array functions.

ArgumentsCopy Anchor Link

• text: The input string
• match: The string used to split the input text string

ReturnsCopy Anchor Link

An enumeration of the substrings

ExamplesCopy Anchor Link

input

{{ for word in "Hi, how are you today?" | string.split ' ' ~}}
{{ word }}
{{ end ~}}

output

Hi, how are you today?

string.starts_withCopy Anchor Link

string.starts_with <text> <value>

DescriptionCopy Anchor Link

Returns a boolean indicating whether the input string starts with the specified string value.

ArgumentsCopy Anchor Link

• text: The input string
• value: The string to look for

ReturnsCopy Anchor Link

if text starts with the specified string value

ExamplesCopy Anchor Link

input

{{ "This is easy" | string.starts_with "This" }}

output

true

string.stripCopy Anchor Link

string.strip <text>

DescriptionCopy Anchor Link

Removes any whitespace characters on the left and right side of the input string.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The input string without any left and right whitespace characters

ExamplesCopy Anchor Link

input

{{ '   too many spaces           ' | string.strip  }}

Highlight to see the empty spaces to the right of the string output

too many spaces

string.strip_newlinesCopy Anchor Link

string.strip_newlines <text>

DescriptionCopy Anchor Link

Removes any line breaks/newlines from a string.

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The input string without any breaks/newlines characters

ExamplesCopy Anchor Link

input

{{ "This is a string.\r\n With \nanother \rstring" | string.strip_newlines  }}

output

This is a string. With another string

string.to_intCopy Anchor Link

string.to_int <text>

DescriptionCopy Anchor Link

Converts a string to an integer

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

A 32 bit integer or null if conversion failed

ExamplesCopy Anchor Link

input

{{ "123" | string.to_int + 1 }}

output

124

string.to_longCopy Anchor Link

string.to_long <text>

DescriptionCopy Anchor Link

Converts a string to a long 64 bit integer

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

A 64 bit integer or null if conversion failed

ExamplesCopy Anchor Link

input

{{ "123678912345678" | string.to_long + 1 }}

output

123678912345679

string.to_floatCopy Anchor Link

string.to_float <text>

DescriptionCopy Anchor Link

Converts a string to a float

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

A 32 bit float or null if conversion failed

ExamplesCopy Anchor Link

input

{{ "123.4" | string.to_float + 1 }}

output

124.4

string.to_doubleCopy Anchor Link

string.to_double <text>

DescriptionCopy Anchor Link

Converts a string to a double

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

A 64 bit float or null if conversion failed

ExamplesCopy Anchor Link

input

{{ "123.4" | string.to_double + 1 }}

output

124.4

string.truncateCopy Anchor Link

string.truncate <text> <length> <ellipsis>?

DescriptionCopy Anchor Link

Truncates a string down to the number of characters passed as the first parameter. An ellipsis (...) is appended to the truncated string and is included in the character count

ArgumentsCopy Anchor Link

• text: The input string
• length: The maximum length of the output string, including the length of the ellipsis
• ellipsis: The ellipsis to append to the end of the truncated string

ReturnsCopy Anchor Link

The truncated input string

ExamplesCopy Anchor Link

input

{{ "The cat came back the very next day" | string.truncate 13 }}

output

The cat ca...

string.truncatewordsCopy Anchor Link

string.truncatewords <text> <count> <ellipsis>?

DescriptionCopy Anchor Link

Truncates a string down to the number of words passed as the first parameter. An ellipsis (...) is appended to the truncated string.

ArgumentsCopy Anchor Link

• text: The input string
• count: The number of words to keep from the input text string before appending the ellipsis
• ellipsis: The ellipsis to append to the end of the truncated string

ReturnsCopy Anchor Link

The truncated input string

ExamplesCopy Anchor Link

input

{{ "The cat came back the very next day" | string.truncatewords 4 }}

output

The cat came back...

string.upcaseCopy Anchor Link

string.upcase <text>

DescriptionCopy Anchor Link

Converts the string to uppercase

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The input string upper case

ExamplesCopy Anchor Link

input

{{ "test" | string.upcase }}

output

TEST

string5Copy Anchor Link

string5 <text>

DescriptionCopy Anchor Link

Computes the md5 hash of the input string

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The md5 hash of the input string

ExamplesCopy Anchor Link

input

{{ "test" | string5 }}

output

098f6bcd4621d373cade4e832627b4f6

string.sha1Copy Anchor Link

string.sha1 <text>

DescriptionCopy Anchor Link

Computes the sha1 hash of the input string

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The sha1 hash of the input string

ExamplesCopy Anchor Link

input

{{ "test" | string.sha1 }}

output

a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

string.sha256Copy Anchor Link

string.sha256 <text>

DescriptionCopy Anchor Link

Computes the sha256 hash of the input string

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The sha256 hash of the input string

ExamplesCopy Anchor Link

input

{{ "test" | string.sha256 }}

output

9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

string.sha512Copy Anchor Link

string.sha512 <text>

DescriptionCopy Anchor Link

Computes the sha512 hash of the input string

ArgumentsCopy Anchor Link

• text: The input string

ReturnsCopy Anchor Link

The sha512 hash of the input string

ExamplesCopy Anchor Link

input

{{ "test" | string.sha512 }}

output

ee26b0dd4af7e749aa1a8ee3c10ae9923f618980772e473f8819a5d4940e0db27ac185f8a0e1d5f84f88bc887fd67b143732c304cc5fa9ad8e6f57f50028a8ff

string.hmac_sha1Copy Anchor Link

string.hmac_sha1 <text> <secretKey>

DescriptionCopy Anchor Link

Converts a string into a SHA-1 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the function.

ArgumentsCopy Anchor Link

• text: The input string
• secretKey: The secret key

ReturnsCopy Anchor Link

The SHA-1 hash of the input string using a hash message authentication code (HMAC)

ExamplesCopy Anchor Link

input

{{ "test" | string.hmac_sha1 "secret" }}

output

1aa349585ed7ecbd3b9c486a30067e395ca4b356

string.hmac_sha256Copy Anchor Link

string.hmac_sha256 <text> <secretKey>

DescriptionCopy Anchor Link

Converts a string into a SHA-256 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the function.

ArgumentsCopy Anchor Link

• text: The input string
• secretKey: The secret key

ReturnsCopy Anchor Link

The SHA-256 hash of the input string using a hash message authentication code (HMAC)

ExamplesCopy Anchor Link

input

{{ "test" | string.hmac_sha256 "secret" }}

output

0329a06b62cd16b33eb6792be8c60b158d89a2ee3a876fce9a881ebb488c0914

string.hmac_sha512Copy Anchor Link

string.hmac_sha512 <text> <secretKey>

DescriptionCopy Anchor Link

Converts a string into a SHA-512 hash using a hash message authentication code (HMAC). Pass the secret key for the message as a parameter to the function.

ArgumentsCopy Anchor Link

• text: The input string
• secretKey: The secret key

ReturnsCopy Anchor Link

The SHA-512 hash of the input string using a hash message authentication code (HMAC)

ExamplesCopy Anchor Link

input

{{ "test" | string.hmac_sha512 "secret" }}

output

f8a4f0a209167bc192a1bffaa01ecdb09e06c57f96530d92ec9ccea0090d290e55071306d6b654f26ae0c8721f7e48a2d7130b881151f2cec8d61d941a6be88a

string.pad_leftCopy Anchor Link

string.pad_left <text> <width>

DescriptionCopy Anchor Link

Pads a string with leading spaces to a specified total length.

ArgumentsCopy Anchor Link

• text: The input string
• width: The number of characters in the resulting string

ReturnsCopy Anchor Link

The input string padded

ExamplesCopy Anchor Link

input

hello{{ "world" | string.pad_left 10 }}

output

hello world

string.pad_rightCopy Anchor Link

string.pad_right <text> <width>

DescriptionCopy Anchor Link

Pads a string with trailing spaces to a specified total length.

ArgumentsCopy Anchor Link

• text: The input string
• width: The number of characters in the resulting string

ReturnsCopy Anchor Link

The input string padded

ExamplesCopy Anchor Link

input

{{ "hello" | string.pad_right 10 }}world

output

hello world

string.base64_encodeCopy Anchor Link

string.base64_encode <text>

DescriptionCopy Anchor Link

Encodes a string to its Base64 representation. Its character encoded will be UTF-8.

ArgumentsCopy Anchor Link

• text: The string to encode

ReturnsCopy Anchor Link

The encoded string

ExamplesCopy Anchor Link

input

{{ "hello" | string.base64_encode }}

output

aGVsbG8=

string.base64_decodeCopy Anchor Link

string.base64_decode <text>

DescriptionCopy Anchor Link

Decodes a Base64-encoded string to a byte array. The encoding of the bytes is assumed to be UTF-8.

ArgumentsCopy Anchor Link

• text: The string to decode

ReturnsCopy Anchor Link

The decoded string

ExamplesCopy Anchor Link

input

{{ "aGVsbG8=" | string.base64_decode }}

output

hello

string.index_ofCopy Anchor Link

string.index_of <text> <search> <startIndex>? <count>? <stringComparison>?

DescriptionCopy Anchor Link

Reports the zero-based index of the first occurrence of the specified string in this instance. The search starts at a specified character position and examines a specified number of character positions.

ArgumentsCopy Anchor Link

• text: The string to search
• search: The string to find the index of.
• startIndex: If provided, the search starting position. If , search will start at the beginning of .
• count: If provided, the number of character positions to examine. If , all character positions will be considered.
• stringComparison: If provided, the comparison rules for the search. If , Allowed values are one of the following: 'CurrentCulture', 'CurrentCultureIgnoreCase', 'InvariantCulture', 'InvariantCultureIgnoreCase', 'Ordinal', 'OrdinalIgnoreCase'

ReturnsCopy Anchor Link

The zero-based index position of the parameter from the start of if is found, or -1 if it is not. If value is , the return value is (if is not provided, the return value would be zero).

ExamplesCopy Anchor Link