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.

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.

length(value)

length('hello')

5

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

2

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

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 NaN or 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?.

present?(value)

present?('SO-1001')

true

present?('   ')

false

present?(null)

false

present?([])

false

present?(false)

true

presence ​

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

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, NaN, Infinity, down to a single null. This lets the fallback operator | catch all of them at once:

presence(_.nickname) | 'none'

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

presence(value)

presence('SO-1001')

SO-1001

presence('   ')

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

{
  "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

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

Output

[
  {"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.

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.

type_of(value)

type_of('SO-1001')

String

type_of(42)

Integer

type_of(Decimal('1.50'))

Decimal

type_of([1])

List

type_of({a: 1})

Map

type_of(null)

Null

Related ​

• Data types: The 16 WEL data types and when to use each one.
• Operators: More information about the fallback operator |.
• Deep map functions: Use type_of inside condition lambdas.
• Unicode functions: Count text the way a reader sees it.