# String functions String functions are used to manipulate string data. These are the string functions you can use with Digibee's Double Braces language:
FunctionDescription
CAPITALIZECapitalizes the first character of a string
LOWERCASEConverts all characters to lowercase
UPPERCASEConverts all characters to uppercase
NORMALIZETransforms special characters into non-special characters
CONTAINSChecks if a substring is contained in a given string
INDEXOFReturns the index of the first occurrence of a substring
LASTINDEXOFReturns the index of the last occurrence of a substring
MATCHESChecks if a string matches a regular expression
STRINGMATCHESReturns all matched expressions in a string that satisfy a pattern
FUZZYMATCHPerforms an approximate comparison between a string and a list of candidates
CONCATConcatenates any number of strings into a single string
CONCATWITHOUTTABConcatenates strings and replaces tab characters with spaces
JOINConcatenates a list of strings with a specified separator
REPLACEReplaces all occurrences of a substring based on a regular expression
SPLITSplits a string into an array based on a regular expression
SUBSTRINGExtracts a substring from a given string
TRIMRemoves blank spaces at the beginning and end of a string
LEFTPADFills the left side of a string with a character to a specific length
RIGHTPADFills the right side of a string with a character to a specific length
ESCAPEEncodes a string using escape sequences
UNESCAPEUnencodes a string that has escape sequences
DEFAULTReturns a default value for null or nonexistent references
TOSTRINGConverts an object to its string representation
RANDOMSTRINGSGenerates random strings given a charset and length
## **Case and normalization** ### **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!" ``` ### **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!" ``` ### **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!" ``` ### **NORMALIZE** Transforms 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" ``` ## **Search and matching** ### **CONTAINS** Checks if a substring is contained in a given string. #### **Syntax** ``` CONTAINS(main_string: string, sub_string: string) -> boolean ``` * `main_string`: the main string to search in. * `sub_string`: the substring to search for. **Returns:** `true` if the substring is found in the main string, `false` otherwise. #### **Usage example** ``` {{ CONTAINS("Hello, world!", "world") }} ``` The expected result is: ``` true ``` ### **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) -> int ``` * `main_string`: the main string to search in. * `sub_string`: 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** **1. Substring found** ``` {{ INDEXOF("Hello, world!", "world") }} ``` The expected result is: ``` 7 ``` **2. Substring not found** ``` {{ INDEXOF("Hello, world!", "welcome") }} ``` The expected result is: ``` -1 ``` ### **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`: the main string to search in. * `sub_string`: 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** **1. Substring found** ``` {{ LASTINDEXOF("Hello, world!", "o") }} ``` The expected result is: ``` 8 ``` **2. Substring not found** ``` {{ LASTINDEXOF("Hello, world!", "a") }} ``` Because the substring `"a"` is not contained in the string `"Hello, world!"`, the expected result is: ``` -1 ``` ### **MATCHES** Checks if a string matches a regular expression. #### **Syntax** ``` MATCHES(value: string, pattern: string) -> boolean ``` * `value`: the string to match against the given regular expression. * `pattern`: the regular expression pattern 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 ``` ### **STRINGMATCHES** Returns an array of all the matched expressions in a string that satisfy a given pattern. #### **Syntax** {% code overflow="wrap" %} ``` STRINGMATCHES(value: string, pattern: string, patternFlag: string) -> Array[string] ``` {% endcode %} * `value`: the string to search for matches. * `pattern`: the regular expression pattern to match against the string. * `patternFlag`: controls the behavior of the regular expression engine, such as case-insensitive matching, multi-line matching, or extended syntax. If not specified, the regular expression engine uses its default behavior. Options are: | Flag | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CANON_EQ` | Activates canonical equivalence matching of Unicode characters. Characters that look identical are matched even if they have different Unicode codepoints. | | `CASE_INSENSITIVE` | Deactivates case sensitivity. | | `COMMENTS` | Allows comments in the regular expression pattern. Comments can be added after a hashtag `#`. | | `DOTALL` | Activates "dotall" mode, allowing a dot `.` to match the newline character `\n`. | | `LITERAL` | Treats the pattern as a sequence of literal characters. Metacharacters or escape sequences are given no special meaning. | | `MULTILINE` | Activates 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 end 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"] ``` ### **FUZZYMATCH** Performs an approximate comparison between a reference string and a list of candidates based on similarity. #### **Syntax** ``` FUZZYMATCH(inputString, threshold, candidateOrArray1, candidateOrArray2, ...) ``` * **`inputString`**: The reference string for comparison. If `null`, it is treated as an empty string and execution is not stopped. * **`threshold`**: A number between `0` and `1` that defines the minimum similarity (for example, 0.8 for 80%). The value must be a JSON number, not a string. Passing `"0.8"` (quoted) raises a type error. Values outside the `[0, 1]` range also raise an error. * **`candidates`**: One or more arguments after the threshold, each of which can be a **string**, a **JSON array**, or any other JSON value (numbers, booleans, objects). Non-string values are converted to their JSON string representation before comparison. When an argument is an array, each of its first-level elements is evaluated as an independent candidate. Scalars and arrays can be mixed in the same call, and **at least one candidate must be provided**.\ Array expansion happens only at the first level: if an element of the array is itself an array or an object, it is treated as a single candidate and its JSON serialization is what gets compared. **Returns:** an array of strings containing the candidates that have a similarity **greater than or equal to** the provided `threshold`, sorted by **descending similarity** (the most similar first). The returned values preserve their original formatting (case and accents). Similarity is computed as `1 −` (`Levenshtein distance / max length of normalized strings`). A score of `1` means identical strings (after normalization); a score of `0` means completely different strings. {% hint style="info" %} For score calculation, the function applies the following normalization to both the input string and each candidate before comparing them: * converts text to lowercase (case-insensitive), * removes diacritics (accents), * replaces punctuation with spaces, * collapses multiple spaces into a single space, and trims leading/trailing whitespace. Normalization affects only the score calculation. The original candidate text is preserved in the returned array. {% endhint %} #### **Usage examples**
Match with normalization (case and accents) Even with accentuation differences in the candidate, normalization allows a match if the threshold is met. * **Expression:** `{{ FUZZYMATCH("ACME CORPORATION", 0.9, "ÁCME CORPÔRATION") }}` * **Result:** `["ÁCME CORPÔRATION"]`
Multiple candidates with sorting The function filters out candidates that do not meet the minimum threshold and sorts the results by proximity score. * **Expression:** `{{ FUZZYMATCH("Acme Corp", 0.5, "Globex", "Acme Corporation", "Aacme Corp") }}` * **Result:** `["Aacme Corp", "Acme Corporation"]`
Strict threshold (no match) If no candidate reaches the minimum similarity, an empty array is returned. * **Expression:** `{{ FUZZYMATCH("Apple", 0.9, "Pineapple", "Banana") }}` * **Result:** `[]`
Array as candidates Pass an array variable directly. Each element is evaluated as an independent candidate. * **Expression:** `{{ FUZZYMATCH("ACME", 0.9999, message.array) }}` * **Result:** Elements of `message.array` that meet the threshold, sorted by descending similarity.
Mixed scalar and array candidates Scalars and arrays can be combined in the same call and are evaluated together. * **Expression:** `{{ FUZZYMATCH("ACME", 0.9, "ACME FIXED", message.otherArray) }}` * **Result:** All candidates from both sources that meet the threshold, sorted by descending similarity.
Empty array An empty array does not add candidates and does not cause an error. * **Expression:** `{{ FUZZYMATCH("ACME", 0.99, []) }}` * **Result:** `[]`
Parameter error handling The function requires at least 3 parameters (input, threshold, and 1 candidate). * **Expression:** `{{ FUZZYMATCH("test", 0.8) }}` * **Result:** `Error: Wrong number of parameters for function FUZZYMATCH expected at least 3 mandatory but got 2`
Nested array (single candidate, no expansion) Only the first level of an array argument is expanded. A nested array is treated as one candidate and its JSON serialization is compared. * **Expression:** `{{ FUZZYMATCH("a,b", 0.99, [["a", "b"], "c"]) }}` * **Result:** `[]` The inner `["a", "b"]` is compared as the literal string `'["a","b"]'`, not as the candidates `"a"` and `"b"` separately.
Invalid threshold The threshold must be a number within the inclusive range `[0, 1]`. Any other value raises an error. * **Expression:** `{{ FUZZYMATCH("a", 1.5, "a") }}` * **Result:** `Error: FUZZYMATCH threshold must be between 0 and 1, got 1.5`
Null input is treated as an empty string Null inputs do not stop execution. They are normalized to an empty string before comparison, and candidates are scored against that empty string. * **Expression:** `{{ FUZZYMATCH(null, 0.0, "anything") }}` * **Result:** `["anything"]` {% hint style="info" %} With threshold `0`, every candidate matches because any similarity (including `0.0`) satisfies the condition. With a higher threshold, the result is typically `[]` because the empty input has very low similarity to non-empty candidates. {% endhint %}
## **Concatenation and joining** ### **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!" ``` ### **CONCATWITHOUTTAB** Concatenates two or more strings and replaces every tab character (`\t`) with a single space ( ). #### **Syntax** ``` CONCATWITHOUTTAB([, , ..., ]) ``` * ``, ``, ..., ``: one or more text expressions. * Brackets `[ ]` indicate that additional parameters are optional. #### **Usage example** ``` "hi": {{ CONCATWITHOUTTAB("Hello", "\tWorld")}}} ``` The expected result is: ```json { "hi": "Hello World" } ``` ### **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`: 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**
Separator as space ``` {{ JOIN(" ", "These","words", "are", "separated","by","spaces") }} ``` The expected result is: ``` "These words are separated by spaces" ```
Separator as hyphen ``` {{ JOIN("-", "These","words", "are","separated","by","hyphens") }} ``` The expected result is: ``` "These-words-are-separated-by-hyphens" ```
## **Transformation** ### **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`: the regular expression pattern that specifies the substring to search for. * `replacement`: the 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!" ``` ### **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`: the 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!"] ``` ### **SUBSTRING** Extracts a substring from a given string. #### **Syntax** {% code overflow="wrap" %} ``` SUBSTRING(value: string, start: int, end: int, throwIndexOutOfBoundError: boolean) -> string ``` {% endcode %} * `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 ends 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" ``` ### **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!" ``` ### **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) -> 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**
String shorter than the target length ``` {{ LEFTPAD("example", 10, "-") ``` The expected result is: ``` "---example" ```
String already at the target length ``` {{ LEFTPAD("hello", 5, "*") ``` Because `"hello"` already has 5 characters, the expected result is: ``` "hello" ```
### **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) -> 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**
String shorter than the target length ``` {{ RIGHTPAD("example", 10, "-") }} ``` The expected result is: ``` "Example---" ```
String already at the target length ``` {{ RIGHTPAD("hello", 5, "*") }} ``` Because `"hello"` already has 5 characters, the expected result is: ``` "hello" ```
## **Encoding** ### **ESCAPE** Encodes a string using escape sequences. #### **Syntax** ``` ESCAPE(value: string, escapeType: string) -> 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("

Hello, world!

", "HTML") }} ``` The expected result is: ``` "<h1>Hello, world!</h1>" ``` ### **UNESCAPE** Unencodes a string that has escape sequences. #### **Syntax** ``` UNESCAPE(value: string, escapeType: string) -> 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: ``` "

Hello, world!

" ``` ## **Utility** ### **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: ```json { "name" : "John Doe", "age" : null } ``` You can use the DEFAULT function to replace the null value with a "not available" string. ```json { "name" : "John Doe", "age" : {{ DEFAULT(message.age, "not available") }} } ``` The expected result is: ```json { "name" : "John Doe", "age" : "not available" } ``` Read this article to learn more about [referencing data with Double Braces](/documentation/connectors-and-triggers/double-braces/how-to-reference-data-using-double-braces.md). ### **TOSTRING** Converts 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" ``` ### **RANDOMSTRINGS** Generates 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" ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digibee.com/documentation/connectors-and-triggers/double-braces/double-braces-functions/string-functions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.