Text Functions

Overview

Text functions compare and transform strings.

The functions are null-safe - they return 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

If string s length exceeds i characters, this function truncates s to the specified number of characters and returns it as the result.

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. The function 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: this function also 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.

The function 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.

If p is empty or null or if p is not found, the function returns the original string s unchanged.

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.

If p is empty, null, or unable to be found, the function returns the original string s unchanged.

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.

If p is empty, null, or unable to be found, the function returns the original string s unchanged.

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.

If p is empty, null, or unable to be found, the function returns the original string s unchanged.

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.

If p is empty, null, or unable to be found, the function returns the original string s unchanged.

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

Replace 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 desired 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.

If the substring p is not found, -1 is returned.

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

Same as indexOf().

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())