Text Functions

Overview

These functions compare and transform strings, null-safe: returns null or false if one of the inputs is null.

Reference

upper

upper(string s) string

Converts string s to uppercase letters.

lower

lower(string s) string

Converts string s to lowercase letters.

truncate

truncate(string s, integer i) string

Truncates s to the specified number of characters and returns the string as the result if string s length exceeds i characters.

startsWith

startsWith(string s, string w) boolean

Returns true if s starts with w.

endsWith

endsWith(string s, string w) boolean

Returns true if s ends with w.

split

split(string s, string p) [string]

Splits string s into a collection of strings using separator p.

// Returns ['Hello', 'world']
split('Hello world', ' ')

Use double quotes ("escaped_text") as escape characters.

// Returns ['Hello', 'new world']
split('hello "new world"', ' ')

To check the size of the returned collection, use the .size() method.

To access the n-th element in the collection, use square brackets [index] or get(index) method, starting with 0 for the first element.

authors = split(tags.authors, ',')
authors.size() == 0 ? 'n/a' : authors[0]

list

list(string s[, string p]) [string]

Splits string s using separator p (default is comma ',') into an array of string values, discards duplicate items by retaining only the first occurrence of each element.

Unlike the split() function, list() does not support double quotes as escape characters.

Example:

// Returns ['hello', '"brave', 'new', 'world"']
list('hello "brave new world" hello', ' ')

ifEmpty

ifEmpty(string a, string b) object

Returns b if a is either null or an empty string.

Note: Accepts arguments of other data types, such as objects and numbers.

Examples:

/* Returns 'N/A' if tags.location is null or empty. Otherwise returns the value of `location` tag. */
ifEmpty(tags.location, 'N/A')

coalesce

coalesce([string] c) string

Returns first non-empty string from the collection or array of strings c.

Returns an empty string if all elements of c are null or empty.

Examples:

// Returns 'string-3'.
coalesce(['', null, 'string-3'])
// Returns the value of `location` tag if the tag value is not empty, otherwise 'SVL' is returned.
coalesce([tags.location, 'SVL'])
/* Returns the value of the entity label if the label is not empty, otherwise the entity name is returned.
If both fields are empty, an empty string is returned. */
coalesce([entity.label, entity])

keepAfter

keepAfter(string s, string p) string

Removes part of the string s before the first occurrence of the given substring p.

Returns the original string s unchanged, if p is empty or null or if p is not found.

Example:

// Returns 'new.world'
keepAfter("hello.new.world", ".")

keepAfterLast

keepAfterLast(string s, string p) string

Removes the part of string s before the last occurrence of the given substring p.

Returns the original string s unchanged, if p is empty or null or if p is not found.

Example:

// Returns 'world'
keepAfterLast("hello.new.world", ".")

keepBefore

keepBefore(string s, string p) string

Removes part of the string s that starts with the first occurrence of the given substring p.

Returns the original string s unchanged, if p is empty or null or if p is not found.

Example:

// Returns 'hello'
keepBefore("hello.new.world", ".")

keepBeforeLast

keepBeforeLast(string s, string p) string

Removes part of the string s that starts with the last occurrence of the given substring p.

Returns the original string s unchanged, if p is empty or null or if p is not found.

Example:

// Returns 'hello.new'
keepBeforeLast("hello.new.world", ".")

replace

replace(string s, string p, string r) string

Replaces all occurrences of the given substring p in the original string s with a second substring r.

Returns the original string s unchanged, if p is empty or null or if p is not found.

Examples:

// Returns 'hello.ne2.2orld'
replace("hello.new.world", "w", "2")

capFirst

capFirst(string s) string

Capitalizes the first letter in the string.

Example:

// Returns 'Hello world'
capFirst("hello world")

capitalize

capitalize(string s) string

Capitalizes the first letter in all words in the string.

Example:

// Returns 'Hello World'
capitalize("hello world")

removeBeginning

removeBeginning(string s, string r) string

Removes substring r from the beginning of string s.

Examples:

// Returns 'llo world'
removeBeginning("hello world", "he")
// Returns 'hello world'
removeBeginning("hello world", "be")

removeEnding

removeEnding(string s, string r) string

Removes given substring r from the end of string s.

// Returns 'hello wor'
removeEnding("hello world", "ld")
// Returns 'hello world'
removeEnding("hello world", "LD")

urlencode

urlencode(string s) string

Replaces special characters in string s with URL-safe characters using percent-encoding ("%" followed by 2 digits).

// Returns 'hello%20world'
urlencode("hello world")

jsonencode

jsonencode(string s) string

Escapes special JSON characters in string s such as double quotes with a backslash to safely include the string within a JSON object.

htmlDecode

htmlDecode(string s) string

Replaces HTML entities in string s with their corresponding characters.

Example:

// Returns 'hello > world'
htmlDecode("hello > world")

unquote

unquote(string s) string

Removes leading and trailing double and single quotation marks from string s.

// Returns 'hello world'
unquote('"hello world"')

countMatches

countMatches(string s, string p) int

Counts how many times the substring p appears in input string s.

Example:

// Return 2
countMatches("hello world", "o")

abbreviate

abbreviate(string s, integer n) string

Truncates string s using ellipses to hide extraneous text. n is the maximum length of the output string.

The minimum length of the output string is 4 characters: 1 character is string s plus 3 characters used for ellipses (...).

Integer n must be set greater than 3 otherwise an exception is raised.

// Returns 'hel...'
abbreviate("hello world", 6)
// Returns 'hello...'
abbreviate("hello world", 8)
// Returns 'hello world'
abbreviate("hello world", 100)
// IllegalArgumentException
abbreviate("abcdefg", 3)

indexOf

indexOf(string s, string p[, int i]) integer

Returns the integer index starting with 0 of the first occurrence of substring p contained in string s starting with index i.

Returns -1 if the substring p is not found.

Examples:

// Returns 0
indexOf("hello world", "h")
// Returns -1
indexOf("hello world", "Z")
// Returns 8
indexOf("hello world", "o", 5)
// Returns -1
indexOf("hello world", "o", 10)

locate

locate(string s, string p[, int i]) integer

Returns the integer index starting with 0 of the first occurrence of substring p contained in string s starting with index i.

Returns -1 if the substring p is not found.

trim

trim(string s) string

Removes leading and trailing non-printable characters.

// Returns 'hello world'
trim(" hello world    ")

length

length(string s) string

Returns the length of string s. If string s is null, function returns -1.

concat

concat([string] c [, string s]) string

Joins the elements of the collection c into a single string containing the elements separated by the optional delimiter s.

  • The default delimiter is comma (,).
  • The delimiter is inserted between the elements.
  • null objects or empty strings within the collection are represented by empty strings.
// Returns 'a:b'
concat(['a', 'b'], ':')
// Returns 'a--b'
concat(['a', null, 'b'], '-')

concatLines

concatLines([string] c) string

Joins the elements of the collection c into a single string containing the elements separated by line breaks \n.

  • null objects or empty strings within the collection are represented by empty lines.
/* For entity.tags map containing {"location": "NUR", "state": "CA"},
the function returns text consisting of two lines:
      NUR
      CA */
concatLines(entity.tags.values())
/*For entity.tags map containing {"location": "NUR", "state": "CA"},
the function returns text consisting of two lines:
      location
      state*/
concatLines(entity.tags.keys())