Common functions ​

Common functions work on values of any type. Almost every transformation needs to know whether a usable value is present and what type it's holding, and these functions answer both. They are the backbone of writing expressions that survive imperfect inbound data.

Access an element or key ​

The following function reads one element out of a List or Map:

at ​

Returns the element of a List at an index, or the value of a Map at a key.

at behaves the same whether collection is a List or a Map. Refer to List functions and Map functions for type-specific examples and related functions like find_by and pluck.

wel
at(collection, index)
ParameterDescription
collectionThe List or Map to read from. Other collection types raise E100.
indexAn Integer position for a List, or a String key for a Map. A negative index counts back from the end, so -1 is the last element in a List.
An index outside the List raises E201, and an index outside the 64-bit range raises E211. A Map key matches exactly, so a key present with a null value returns null rather than raising an error, and a missing key raises catchable E104.
Get a list element by position

The following example returns the element at index 0:

Formula

wel
at(['pending', 'shipped', 'closed'], 0)

Output

text
pending
Get a map value by key

The following example returns the value at a key:

Formula

wel
at({sku: 'WID-1', qty: 3}, 'qty')

Output

wel
3

Measure ​

The following function measures the size of a value, in the unit appropriate to its type:

length ​

Returns the length of a String in code points, the number of elements in a List, or the number of keys in a Map.

length counts code points, not bytes, for a string. Some emoji and accented letters are made of several code points combined into a single user-perceived character (grapheme cluster). Refer to Unicode functions for grapheme clusters.

wel
length(value)
ParameterDescription
valueA String, List, or Map. Any other type, including null and Binary, raises E100.
Count code points in a string

The following example counts each code point in the string:

Formula

wel
length('hello')

Output

wel
5
Count elements in a list

The following example counts each element in the list:

Formula

wel
length(['a', 'b'])

Output

wel
2
Count keys in a map

The following example counts each key in the map:

Formula

wel
length({a: 1, b: 2, c: 3})

Output

wel
3

Test for a usable value ​

The following functions test whether a value is actually usable, not just non-null:

present? ​

Returns true when a value is actually usable: Not null, not empty, not whitespace-only, and not Infinity. Works on every data type.

false returns as true because it's a meaningful value in a pipeline, not an absence. This differs from Ruby's blank?.

wel
present?(value)
ParameterDescription
valueAny value except a Regex, which raises E100.
A non-empty string is present

The following example tests a non-empty string:

Formula

wel
present?('SO-1001')

Output

wel
true
A whitespace-only string isn't present

The following example tests a whitespace-only string:

Formula

wel
present?('   ')

Output

wel
false
Null isn't present

The following example tests a null value:

Formula

wel
present?(null)

Output

wel
false
An empty list isn't present

The following example tests an empty list:

Formula

wel
present?([])

Output

wel
false
False is present

The following example tests a boolean false value, which is meaningful data, not an absence:

Formula

wel
present?(false)

Output

wel
true

presence ​

Returns the value when it's present, and null when it isn't or when the value is Skip.

presence is the companion to present?, and the two are for different jobs. present? gives you a Boolean to branch on. presence normalizes every kind of absence: Empty string, whitespace-only string, empty list or map, Infinity, down to a single null. This lets the fallback operator | catch all of them at once:

wel
presence(_.nickname) | 'none'

Without presence, a field containing ' ' isn't null, so | would pass the whitespace straight through.

wel
presence(value)
ParameterDescription
valueAny value except a Regex, which raises E100.
A usable value passes through unchanged

The following example passes a usable value through unchanged:

Formula

wel
presence('SO-1001')

Output

text
SO-1001
A whitespace-only string normalizes to null

The following example normalizes a whitespace-only string to null:

Formula

wel
presence('   ')

Output

wel
null

Use case: Pick the first name that is actually filled in ​

A CRM export supplies a display name that is sometimes blank and a legal name that is sometimes missing. Chain presence with | to fall through to the first usable one:

Input

json
{
  "contacts": [
    {"id": "C-1", "display_name": "  ", "legal_name": "Kalani Park"},
    {"id": "C-2", "display_name": "Noam", "legal_name": "Noam Gupta"},
    {"id": "C-3", "display_name": null, "legal_name": null}
  ]
}

Formula

wel
_.contacts >> map_by(c ~> {
  id: c.id,
  name: presence(c.display_name) | presence(c.legal_name) | 'Unknown'
})

Output

json
[
  {"id": "C-1", "name": "Kalani Park"},
  {"id": "C-2", "name": "Noam"},
  {"id": "C-3", "name": "Unknown"}
]

C-1 falls through because ' ' is blank rather than missing, exactly the case a plain null check would let slip through to the destination.

Inspect a type ​

The following function reports which of the 16 WEL types a value actually is:

type_of ​

Returns the name of a value's type as a String. Calling type_of on a lambda raises E107.

Most useful for writing condition lambdas, which decide which leaves of a payload a rule should apply to, and for diagnosing a transformation that is failing on unexpected input.

wel
type_of(value)
ParameterDescription
valueAny value.
A string

The following example returns the type of a string:

Formula

wel
type_of('SO-1001')

Output

text
String
An integer

The following example returns the type of an integer:

Formula

wel
type_of(42)

Output

text
Integer
A decimal

The following example returns the type of a decimal:

Formula

wel
type_of(Decimal('1.50'))

Output

text
Decimal
A list

The following example returns the type of a list:

Formula

wel
type_of([1])

Output

text
List
A map

The following example returns the type of a map:

Formula

wel
type_of({a: 1})

Output

text
Map
Null

The following example returns the type of a null value:

Formula

wel
type_of(null)

Output

text
Null

TYPE_OF REPORTS WHAT YOU ACTUALLY HAVE

type_of(42) is Integer and type_of(Decimal('1.50')) is Decimal, even though both look like numbers. Check the type when arithmetic produces a result you didn't expect. It's the recommended way to determine why. Refer to Data types for what each WEL type represents.

Last updated: