String functions

Learn about string functions in the Digibee Integration Platform and how to use them.

String functions are used to manipulate string data. These are the string functions you can use with Digibee's Double Braces language:

CAPITALIZE

Capitalizes the first character of a string. Other characters are not affected.

Syntax

CAPITALIZE(value : string) -> string

• value : the string whose first letter is to be capitalized.

Returns: a string that is a version of value with the first character in upper case.

Usage example

{{ CAPITALIZE("hello, world!") }}

The expected result is:

"Hello, world!"

CONCAT

Concatenates any number of strings into a single string.

Syntax

CONCAT(*values: string) -> string

• values: any number of strings to be concatenated.

Returns: the concatenated string.

Usage example

{{ CONCAT("Hello", ", ", "world!") }}

The expected result is:

"Hello, world!"

CONTAINS

Checks if a substring is contained in a given string.

Syntax

CONTAINS(main_string: string, sub_string: string) -> boolean

• main_string: a string representing the main string to search in.

• sub_string: a string representing the substring to search for.

Returns: a boolean value indicating whether the substring is found or not. true is returned if the substring is found in the main string, and false is returned otherwise.

Usage example

{{ CONTAINS("Hello, world!", "world") }}

The expected result is:

true

DEFAULT

Returns a default value when a reference is made to a null or nonexistent value.

Syntax

DEFAULT(value : string, defaultValue : string) -> string

• value: the value to be checked for null or nonexistence.

• defaultValue: the default value to be returned if value is null or nonexistent.

Returns: either value, if value is not null or nonexistent, or defaultValue, if it is.

Usage example

Suppose you are using this function in the JSON parameter of a JSON Generator component that receives the following payload:

{
"name" : "John Doe",
"age" : null
}

You can use the DEFAULT function to replace the null value with a “not available” string.

{
"name" : "John Doe",
"age" : {{ DEFAULT(message.age, "not available") }}
}

The expected result is:

{
"name" : "John Doe",
"age" : "not available"
}

Read this article to learn more about referencing data with Double Braces.

ESCAPE

Encode a string using escape sequences.

Syntax

ESCAPE(value: string, escapeType: string<optional>) -> string

• value: the string to be encoded.

• escapeType: the type of escaping to be used. Valid options are "JSON", "XML", "CSV", and "HTML". Defaults to “JSON”.

Returns: a new string in which certain characters have been escaped.

Usage example

{{ ESCAPE("<h1>Hello, world!</h1>", "HTML") }}

The expected result is:

"<h1>Hello, world!</h1>"

INDEXOF

Returns the index of the first occurrence of a substring within a given string. This search is case-sensitive and the index starts at 0.

Syntax

INDEXOF(main_string: string, sub_string: string, fromIndex: integer<optional>) -> int

• main_string: a string representing the main string to search in.

• sub_string: a string representing the substring to search for.

• fromIndex: the index from which the search should start. Defaults to 0.

Returns: an integer indicating the index of the first occurrence of the substring in the main string. If the substring is not found, the function returns -1.

Usage examples

{{ INDEXOF("Hello, world!", "world") }}

The expected result is:

7

{{ INDEXOF("Hello, world!", "welcome") }}

The expected result is:

-1

JOIN

Concatenates a list of strings into a single string with a specified separator character between each string.

Syntax

JOIN(separator: string, *values: string) -> string

• separator: a string representing the separator character to be used between each string.

• values: any number of strings to be concatenated.

Returns: a string value representing the concatenated string with the specified separator character between each string in the input list.

Usage examples

{{ JOIN(" ", "These","words", "are", "separated","by","spaces") }}

The expected result is:

"These words are separated by spaces"

{{ JOIN("-", "These","words", "are","separated","by","hyphens") }}

The expected result is:

"These-words-are-separated-by-hyphens"

LASTINDEXOF

Returns the index of the last occurrence of a substring within a given string. This search is case-sensitive and the index starts at 0.

Syntax

LASTINDEXOF(main_string: string, sub_string: string) -> int

• main_string: a string representing the main string to search in.

• sub_string: a string representing the substring to search for.

• fromIndex: the index from which the search should start. Defaults to 0.

Returns: an integer indicating the index of the last occurrence of the substring in the main string. If the substring is not found, the function returns -1.

Usage examples

{{ LASTINDEXOF("Hello, world!", "o") }}

The expected result is:

8

{{ LASTINDEXOF("Hello, world!", "a") }}

Because the substring “a” is not contained in the string “Hello, world!”, the expected result is:

-1

LEFTPAD

Fills the left side of a given string with a specified character to a specific length.

Syntax

LEFTPAD(value: string, length: integer, character:string<optional>) -> string

• value: the input string to be padded.

• length: the length of the desired string.

• character: the character that will be used to pad the left side of the input string. Defaults to a blank space.

Returns: a padded string of the desired length with the specified character filling the left side of the input string. If the input string is already longer than the specified length, the original string is returned.

Usage examples

{{ LEFTPAD("example", 10, "-")

The expected result is:

"---example"

{{ LEFTPAD("hello", 5, "*")

Because “hello” already has 5 characters, the expected result is:

"hello"

LOWERCASE

Converts all characters to lowercase.

Syntax

LOWERCASE(value: string) -> string

• value: the input string to be converted to lowercase.

Returns: the string that is the lowercase equivalent of the input string.

Usage example

{{ LOWERCASE("HELLO, WorLD!") }}

The expected result is:

"hello, world!"

MATCHES

Checks if a string matches a regular expression.

Syntax

MATCHES(value: string, pattern: string) -> boolean

• value: a string that is to be matched against the given regular expression.

• pattern: a regular expression pattern that is to be used to match against the input string.

Returns: true if the input string matches the regular expression, false, otherwise.

Usage example

{{ MATCHES("123-456-7890", "\\d{3}-\\d{3}-\\d{4}") }}

The expected result is:

true

NORMALIZE

Transforms any special characters into non-special characters.

Syntax

NORMALIZE(value: string) -> string

• value: the string to be normalized.

Returns: the normalized string with special characters replaced by their non-special counterparts.

Usage example

{{ NORMALIZE("São Paulo") }}

The expected result is:

"Sao Paulo"

RANDOMSTRINGS

Generate random strings given a charset and string length.

Syntax

RANDOMSTRINGS(charset: string, length: int) -> string

• charset : the charset to be used. Options are: "ALPHANUMERIC”, "ALPHABETIC" "ASCII", and "NUMERIC".

• length: the length of the output string.

Usage example

{{ RANDOMSTRINGS("ALPHANUMERIC",10) }}

The output varies because it is random. One possible output is:

"lUbCIs7T3G"

REPLACE

Replaces all occurrences of a substring in a string based on a given regular expression.

Syntax

REPLACE(value: string, pattern: string, replacement: string) -> string

• value: the string to be searched and altered.

• pattern: a regular expression pattern that specifies the substring to search for.

• replacement: a string that will replace all occurrences of the matched pattern in the input string.

Usage example

{{ REPLACE("Hello, world!", "Hello", "Bonjour") }}

The expected result is:

"Bonjour, world!"

RIGHTPAD

Fills the right side of a given string with a specified character to a specific length.

Syntax

RIGHTPAD(value: string, length: integer, character:string<optional>) -> string

• value: the input string to be padded.

• length: the length of the desired string.

• character: the character that will be used to pad the right side of the input string. Defaults to a blank space.

Returns: a padded string of the desired length with the specified character filling the right side of the input string. If the input string is already longer than the specified length, the original string is returned.

Usage examples

{{ RIGHTPAD("example", 10, "-") }}

The expected result is:

"Example---"

{{ RIGHTPAD("hello", 5, "*") }}

Because “hello” already has 5 characters, the expected result is:

"hello"

SPLIT

Splits a string into an array of strings based on a specified regular expression pattern.

Syntax

SPLIT(value: string, pattern: string) -> Array[string]

• value: the string to be split.

• pattern: a regular expression pattern that specifies the split point. The string will be split at all occurrences of the pattern.

Returns: an array of strings resulting from the split operation.

Usage example

{{ SPLIT("Hello, world!", " ") }}

The expected result is:

["Hello,", "world!"]

STRINGMATCHES

Returns an array of all the matched expressions in a string that satisfy a given pattern.

Syntax

STRINGMATCHES(value: string, pattern: string, patternFlag: string<optional>) -> Array[string]

• value: a string to search for matches.

• pattern: a regular expression pattern to match against the string.

• patternFlag: the behavior of the regular expression engine. This can be used to modify the matching behavior of the regular expression, such as case-insensitive matching, multi-line matching, or extended syntax. If not specified, the regular expression engine uses its default behavior. Options are:

  • CANON_EQ: activate canonical equivalence matching of Unicode characters. When this flag is activated, characters that look identical are matched even if they have different Unicode codepoints.

  • CASE_INSENSITIVE: deactivate case sensitivity.

  • COMMENTS: allow comments in the regular expression pattern. You can add comments after a hashtag #.

  • DOTALL: activate “dotall” mode, that allows a dot . to match the newline character \n.

  • LITERAL: when this flag is specified then the input string that specifies the pattern is treated as a sequence of literal characters. Metacharacters or escape sequences in the input sequence will be given no special meaning.

  • MULTILINE: activate matching across multiple lines.

  • UNICODE_CASE: allows case-insensitive matching of Unicode characters, taking into account Unicode case folding rules.

  • UNICODE_CHARACTER_CLASS: allows Unicode character classes in the regular expression pattern.

  • UNIX_LINES: changes the behavior of the ^ and $ metacharacters to match the beginning and end of a line, respectively, rather than the beginning and ending of the input string.

Returns: an array of all the matched expressions in the string that satisfy the pattern.

Usage example

{{ STRINGMATCHES("Hello, world!", "hello", "CASE_INSENSITIVE") }}

The expected result is:

["Hello"]

SUBSTRING

Extract a substring from a given string.

Syntax

SUBSTRING(value: string, start: int, end: int<optional>, throwIndexOutOfBoundError: boolean<optional>) -> string

• value: the original string from which the substring is to be extracted.

• start: the starting index of the substring. The index starts at 0.

• end: the ending index of the substring. If not provided, the extraction will end at the last character of the original string.

• throwIndexOutOfBoundError: if true, an error will be thrown if the provided indexes are out of range. Otherwise, the original string will be returned. Defaults to true.

Returns: the extracted substring from the original string.

Usage example

{{ SUBSTRING("Hello, world!", 0, 5) }}

The expected result is:

"Hello"

TOSTRING

Convert an object to its string representation.

Syntax

TOSTRING(object: any) -> string

• object: the object to be converted to a string. It can be of any type.

Usage example

{{ TOSTRING(123) }}

The expected result is:

"123"

TRIM

Removes blank spaces at the beginning and end of a string.

Syntax

TRIM(value : string) -> string

• value: the string to be trimmed.

Returns: a string that is a trimmed version of value.

Usage example

{{ TRIM(" Hello, world! ") }}

The expected result is:

"Hello, world!"

UNESCAPE

Unencode a string that has escape sequences.

Syntax

UNESCAPE(value: string, escapeType: string<optional>) -> string

• value: the string to be unencoded.

• escapeType: the type of escaping to be used. Valid options are "JSON", "XML", "CSV", and "HTML". Defaults to “JSON”.

Returns: a new string in which certain characters have been unescaped.

Usage example

{{ UNESCAPE("<h1>Hello, world!</h1>", "HTML") }}

The expected result is:

"<h1>Hello, world!</h1>"

UPPERCASE

Converts all characters to uppercase.

Syntax

UPPERCASE(value: string) -> string

• value: the input string to be converted to uppercase.

Returns: the string that is the uppercase equivalent of the input string.

Usage example

{{ UPPERCASE("Hello, world!") }}

The expected result is:

"HELLO, WORLD!"