String functions ​

String functions read and reshape text. Use them to clean inbound payloads, extract identifiers, normalize values before they reach a destination system, and build the exact string format a target expects.

_ is the input your expression receives in these examples. Refer to Input variables for more information.

Call a string function ​

Call a function directly, or pipe a value into it with >>:

upper(_.status)
_.status >> upper

The pipe form reads left to right, which makes it the better choice when you chain several steps:

_.email >> trim >> lower

The piped value fills the function's first argument. Write any other arguments normally:

_.order_id >> starts_with?('SO-')

Check a string ​

The following functions return a Boolean. Use them in conditions, in filter_by, and to guard a step before it runs.

blank? ​

Returns true if the string is empty or contains only whitespace.

blank?(string)

blank?('   ')

true

blank?('SO-1001')

false

empty? ​

Returns true if the value has no content. It works on a String, List, Map, or Binary value, and unlike blank?, it returns true for null.

empty?(value)

empty?('')

true

empty?(null)

true

contains? ​

Returns true if the string contains the substring, using a case-sensitive comparison.

contains?(string, substring)

contains?('Partner account', 'Partner')

true

contains?('Partner account', 'partner')

false

starts_with? ​

Returns true if the string begins with the prefix.

starts_with?(string, prefix)

starts_with?('SO-1001', 'SO-')

true

ends_with? ​

Returns true if the string ends with the suffix.

ends_with?(string, suffix)

ends_with?('invoice.pdf', '.pdf')

true

valid_email? ​

Returns true if the string is a valid email address, as defined in RFC 5321 and RFC 5322.

valid_email?(string)

valid_email?('[email protected]')

true

valid_email?('nur@@example.com')

false

valid_url? ​

Returns true if the string is a valid URL. Pass a list of schemes to restrict which are accepted.

valid_url?(string)
valid_url?(string, schemes)

valid_url?('https://example.com/orders')

true

valid_url?('ftp://example.com', ['http', 'https'])

false

match? ​

Returns true if the string matches a regular expression. WEL uses ECMAScript regular expression syntax.

match?(string, pattern)

match?('SO-1001', '^SO-\d+$')

true

Use case: Filter a delimited recipient list ​

A webhook delivers recipients as one comma-separated string with inconsistent spacing, casing, and malformed entries. Use string functions to split it, normalize each address, then keep only the valid ones:

Input

{
  "recipients": "[email protected], [email protected] ,,not-an-address"
}

Formula

_.recipients
  >> split(',')
  >> map_by(e ~> trim(e) >> lower)
  >> filter_by(e ~> valid_email?(e))

Output

["[email protected]", "[email protected]"]

split produces four entries, including one empty string. trim and lower normalize each one. valid_email? discards both the empty entry and not-an-address.

Change case ​

The following functions change the case of a string's characters:

upper ​

Converts the string to uppercase.

upper(string)

upper('acme corp')

ACME CORP

lower ​

Converts the string to lowercase. Use it to normalize email addresses and codes before comparing or deduplicating them.

lower(string)

lower('ACME Corp')

acme corp

capitalize ​

Converts the first character to uppercase and the rest to lowercase.

capitalize(string)

capitalize('acme')

Acme

titleize ​

Converts the first character of each whitespace-separated word to uppercase and the rest to lowercase.

titleize(string)

titleize('acme widgets inc')

Acme Widgets Inc

Clean and pad ​

The following functions remove whitespace or pad a string to a fixed width:

trim ​

Removes leading and trailing whitespace.

trim(string)

trim('  SO-1001  ')

SO-1001

ltrim ​

Removes leading whitespace.

ltrim(string)

ltrim('  SO-1001')

SO-1001

rtrim ​

Removes trailing whitespace.

rtrim(string)

rtrim('SO-1001  ')

SO-1001

lpad ​

Pads the start of the string until it reaches the given width. Use it for zero-padded reference numbers and fixed-width records.

lpad(string, width, pad)

lpad('42', 8, '0')

00000042

rpad ​

Pads the end of the string until it reaches the given width.

rpad(string, width, pad)

rpad('A-100', 8, ' ')

"A-100   "

normalize_newlines ​

Rewrites CRLF, CR, and LF line terminators to a single convention. Defaults to LF.

normalize_newlines(string, terminator)

normalize_newlines("a\r\nb\rc")

"a\nb\nc"

Use case: Build a fixed-width record ​

Many ERP and mainframe systems accept fixed-width records rather than JSON. Use string functions to pad each field to its column width, then concatenate them:

Input

{
  "sku": "A-100",
  "qty": 2
}

Formula

rpad(_.sku, 10, ' ') ++ lpad(String(_.qty), 5, '0')

Output

"A-100     00002"

The SKU occupies a 10-character column padded on the right. The quantity occupies a 5-character column zero-padded on the left. qty is an Integer, so String(...) converts it before padding.

Extract part of a string ​

The following functions read or extract part of a string without changing the rest of it:

substring ​

Extracts part of a string by code-point index. A negative start counts back from the end.

substring(string, start, length)

substring('SO-1001', 3)

1001

substring('SO-1001', 0, 2)

SO

substring('SO-1001', -4)

1001

index_of ​

Returns the zero-based index of the first occurrence of a substring, or -1 if it isn't found.

index_of(string, substring)

index_of('orders/SO-1001', '/')

6

split ​

Splits a string into a list on a literal separator.

split(string, separator)

split('[email protected],[email protected]', ',')

["[email protected]", "[email protected]"]

split_regex ​

Splits a string into a list on a regular expression. Use it when the delimiter varies.

split_regex(string, pattern)

split_regex('A-100; B-220,C-050', '[;,]\s*')

["A-100", "B-220", "C-050"]

match ​

Returns the first regular expression match as a map, or null if there is no match. Key 0 is the full match, numeric keys hold each capture group, and named captures are also available by name.

match(string, pattern)

match('SO-1001', '^(?<prefix>[A-Z]+)-(?<number>\d+)$')

{"0": "SO-1001", "1": "SO", "2": "1001", prefix: "SO", number: "1001"}

match_all ​

Returns every regular expression match as a list of maps, using the same key structure as match.

match_all(string, pattern)

match_all('A-100 B-220', '[A-Z]-\d+')

[{"0": "A-100"}, {"0": "B-220"}]

parse_url ​

Parses a URL into its components.

parse_url(string)

parse_url('https://api.example.com:8443/v2/orders?status=open#top')

{scheme: "https", host: "api.example.com", port: 8443, path: "/v2/orders", query: "status=open", fragment: "top"}

Use case: Extract an identifier from a callback path ​

An inbound callback carries the order number inside a URL path. Use a named capture group to pull it out, without depending on the position of the segment:

Input

{
  "path": "/orders/SO-1001/lines"
}

Formula

match(_.path, '/orders/(?<order>[A-Z]{2}-\d+)/').order

Output

"SO-1001"

match returns a map, so the formula reads the order key directly. match returns null if the path can't match, and reading the key then fails as a result. Add a fallback with |? when the source data varies. Refer to the Operators documentation for details.

Replace part of a string ​

WEL has separate functions for literal and regular expression matching. Each comes in a first-match and an all-matches form.

replace_all ​

Replaces every occurrence of a literal substring.

replace_all(string, pattern, replacement)

replace_all('A-100-X', '-', '')

A100X

replace_first ​

Replaces the first occurrence of a literal substring.

replace_first(string, pattern, replacement)

replace_first('A-100-X', '-', '')

A100-X

replace_all_regex ​

Replaces every regular expression match. gsub is an alias.

replace_all_regex(string, pattern, replacement)

replace_all_regex('SO 1001  extra', '\s+', ' ')

SO 1001 extra

gsub('(555) 123-4567', '[^0-9]', '')

5551234567

replace_first_regex ​

Replaces the first regular expression match. sub is an alias.

replace_first_regex(string, pattern, replacement)

sub('SO-1001', '^SO', 'PO')

PO-1001

concat ​

Joins two strings. Use ++ or string interpolation to join more than two, or to mix in other types.

concat(first, second)

concat('Josh', ' Ito')

Josh Ito

_.first_name ++ ' ' ++ _.last_name
"Order ${_.order_id} for ${_.customer}"

Use case: Normalize an inbound contact ​

A signup webhook delivers names with inconsistent spacing and casing, and an email address that a downstream CRM treats as case-sensitive. Use string functions to normalize all three fields before the record is created:

Input

{
  "first_name": "  josh ",
  "last_name": "ITO",
  "email": " [email protected] "
}

Formula

{
  full_name: titleize(trim(_.first_name) ++ ' ' ++ trim(_.last_name)),
  email: lower(trim(_.email))
}

Output

{
  "full_name": "Josh Ito",
  "email": "[email protected]"
}

trim removes whitespace from each field before ++ joins them, so the joining space is the only space between the names. titleize then fixes the casing of both names at once. lower normalizes the address so it matches an existing CRM record regardless of how it was typed.

Related ​

• Data types: Why string functions require a String.
• Strings and formatting: Information about interpolation, f-strings, and format specs.
• Operators: Information about ++, the pipe >>, and the fallback operators.
• Error codes: Troubleshoot job failures such as E100 and E201.