Conversion functions ​

Conversion functions construct values of specific types. Each function uses the name of the type it produces and starts with a capital letter. For example, Decimal('19.99') creates a Decimal value.

Conversion functions give you explicit control over a value's type where inbound data enters an expression, because inbound data usually arrives as strings. WEL doesn't convert an argument to make a call succeed, except for string interpolation and one Transform data flag that configures mixed precision coercion. Explicit conversion at the boundary keeps downstream operations type-safe and predictable.

CONVERT ONCE, AT THE EDGE

Convert each field to its intended type in one place at the start of the transformation. Use those typed values throughout the remaining expression. Scattered conversions through an expression make it hard to see which fields have been handled, and raise the chance that a number gets rounded twice.

Numbers ​

WEL has three numeric constructors, one for each numeric type.

Integer ​

Converts to an Integer. Accepts an existing Integer or a string of digits.

wel
Integer(value)
ParameterDescription
valueAn Integer or an integer string. An integer string can include underscores as separators, such as Integer('1_000_000'). A string that contains anything other than a valid integer raises E102. For example, Integer('3 items') raises an error instead of returning 3.
Convert an integer string

The following example converts an integer string:

Formula

wel
Integer('42')

Output

wel
42
Pass through an existing integer

The following example passes an existing Integer through unchanged:

Formula

wel
Integer(42)

Output

wel
42

Decimal ​

Converts to a Decimal, an exact, arbitrary-precision number.

Use Decimal for money. Pass the value as a string, such as Decimal('19.99'), so the exact digits reach the constructor. Decimal(19.99) converts a Float that's already approximate, which discards the exactness Decimal exists to preserve.

Decimal also preserves scale, so Decimal('12.50') keeps its trailing zero through arithmetic and a total stays a currency amount rather than becoming 12.5.

wel
Decimal(value)
ParameterDescription
valueA number or a numeric string. A string that isn't a valid number, such as Decimal('notanumber'), raises E020.
Convert a decimal string

The following example converts a decimal string:

Formula

wel
Decimal('19.99')

Output

wel
19.99
Convert an integer to a Decimal

The following example converts an integer to a Decimal:

Formula

wel
Decimal(5)

Output

wel
5

Float ​

Converts to a Float, a binary floating-point number.

Appropriate for measurements, ratios, and scientific values, where approximate precision is acceptable. Not appropriate for money, because a Float can't represent most decimal fractions exactly. Refer to Decimal for exact arithmetic instead.

wel
Float(value)
ParameterDescription
valueA number or a numeric string. Enter 'inf' and 'infinity' for an infinite value. 'NaN' and incomplete strings such as '.5' and '5.' raise E102.
Convert a numeric string to a Float

The following example converts a numeric string to a Float:

Formula

wel
Float('3.14')

Output

wel
3.14

Parse formatted numeric text ​

The Integer, Decimal, and Float functions raise an error for inputs that break WEL's numeric grammar, such as zero-padding or a locale-specific separator. Use the functions in this section instead to convert numeric text written with non-WEL grammar.

parse_integer ​

Converts a string of digits into an Integer. Accepts formatting that the stricter Integer constructor rejects, such as zero-padding, a thousands separator, or a different base.

wel
parse_integer(input, options)
ParameterDescription
inputA string of digits. Malformed text, a decimal place, or an exponent raises E225. A non-string argument raises E100.
optionsAn optional map to control how input parses.
  • trim: Allows surrounding whitespace. Defaults to true.
  • underscores: Allows a single underscore (_) between digits, such as '1_000_000'. Defaults to true.
  • decimal_separator: The character to treat as the decimal separator when parsing input. Defaults to the data-plane locale. Must differ from thousands_separator.
  • thousands_separator: The character to treat as the thousands separator when parsing input. Defaults to the data-plane locale. Must differ from decimal_separator. Set to '' to disable digit grouping.
  • base: An integer defining the base to use. Valid values include 2 to 36 (inclusive) and 0. 0 infers the base from a 0b, 0o, or 0x prefix in input and rejects zero-padding without a prefix. decimal_separator and thousands_separator require base 10. Defaults to 10.
An unknown key, an invalid separator, or base: 1 raises E225. An option value of the wrong type raises E218. A base outside 0 to 36, or a value beyond Integer's size limit, raises E211. A non-map options raises E100.
Convert zero-padded text

The following example converts zero-padded text:

Formula

wel
parse_integer('000030')

Output

wel
30
Convert digit-grouped text

The following example converts text grouped with a thousands separator:

Formula

wel
parse_integer('1,000,000', {thousands_separator: ','})

Output

wel
1000000
Convert a hexadecimal string

The following example converts a hexadecimal string:

Formula

wel
parse_integer('ff', {base: 16})

Output

wel
255

parse_decimal ​

Converts numeric text into an exact Decimal that keeps its written scale. Accepts formatting that the stricter Decimal constructor rejects, such as zero-padding or a locale-specific separator.

wel
parse_decimal(input, options)
ParameterDescription
inputA numeric string. parse_decimal also accepts .5, 1., and 1e3. Malformed text, NaN, or infinity raises E225. A non-string argument raises E100.
optionsAn optional map to control how input parses.
  • trim: Allows surrounding whitespace. Defaults to true.
  • underscores: Allows a single underscore (_) between digits. Defaults to true.
  • decimal_separator: The character to treat as the decimal separator when parsing input. Defaults to the data-plane locale. Must differ from thousands_separator.
  • thousands_separator: The character to treat as the thousands separator when parsing input. Defaults to the data-plane locale. Must differ from decimal_separator. Set to '' to disable digit grouping.
An unknown key or an invalid separator raises E225. An option value of the wrong type raises E218. A value beyond Decimal's size limit raises E211. A non-map options raises E100.
Keep scale from zero-padded text

The following example converts zero-padded text and maintains its scale:

Formula

wel
parse_decimal('00012.50')

Output

wel
12.50
Convert a European-formatted amount

The following example converts an amount that uses a comma as the decimal separator and a period to group digits:

Formula

wel
parse_decimal('1.234,56', {decimal_separator: ',', thousands_separator: '.'})

Output

wel
1234.56

parse_float ​

Converts numeric text into a correctly rounded Float. Accepts formatting that the stricter Float constructor rejects, such as zero-padding or a locale-specific separator. Float accepts 'inf' and 'infinity'. parse_float rejects 'inf', 'infinity', 'NaN', and any other non-numeric text.

wel
parse_float(input, options)
ParameterDescription
inputA numeric string. parse_float also accepts .5, 1., and 1e3. A value too small for a Float rounds to zero instead of raising an error. Malformed text, NaN, or infinity raises E225. A non-string argument raises E100.
optionsAn optional map to control how input parses.
  • trim: Allows surrounding whitespace. Defaults to true.
  • underscores: Allows a single underscore (_) between digits. Defaults to true.
  • decimal_separator: The character to treat as the decimal separator when parsing input. Defaults to the data-plane locale. Must differ from thousands_separator.
  • thousands_separator: The character to treat as the thousands separator when parsing input. Defaults to the data-plane locale. Must differ from decimal_separator. Set to '' to disable digit grouping.
An unknown key or an invalid separator raises E225. An option value of the wrong type raises E218. A finite value beyond Float's range raises E211. A non-map options raises E100.
Convert a numeric string

The following example converts a numeric string:

Formula

wel
parse_float('12.50')

Output

wel
12.5
Convert a value too small for a Float

The following example converts a value too small for a Float, which rounds to zero:

Formula

wel
parse_float('1e-400')

Output

wel
0

Text and truth ​

The following constructors convert to String, Bool, and Binary:

String ​

Converts a scalar value to a String, using the data-plane locale.

Rejects Binary and collections. A List or Map isn't turned into a string implicitly or by this function, and passing one raises E100. Use to_json or to_wel to serialize a collection deliberately. This restriction exists because a silently stringified collection is one of the hardest transformation bugs to notice downstream.

wel
String(value)
ParameterDescription
valueA scalar value.
Convert an integer to a string

The following example converts an integer to a string:

Formula

wel
String(42)

Output

wel
42
Convert a Decimal to a string

The following example converts a Decimal to a string:

Formula

wel
String(Decimal('19.99'))

Output

wel
19.99

Bool ​

Converts a value to a Boolean. Accepts an existing Boolean, or the strings 'true' and 'false'.

'yes', '1', and 'Y' aren't accepted because their meaning depends on the source system, and an unrecognized string raises E102. Map source-specific values to a Boolean explicitly:

wel
if _.flag == 'Y' then true else false
wel
Bool(value)
ParameterDescription
valueA Boolean, or the string 'true' or 'false'.
Convert the string 'true'

The following example converts the string 'true' to a Boolean:

Formula

wel
Bool('true')

Output

wel
true

Binary ​

Converts an ASCII string to Binary bytes. An existing Binary value passes through unchanged.

Use encode_string, which takes an explicit encoding, for text that isn't ASCII.

wel
Binary(value)
ParameterDescription
valueAn ASCII string. Non-ASCII strings raise E008. Values that aren't a String or Binary and computed strings that become non-ASCII at runtime raise E100.
Convert an ASCII string to bytes

The following example converts an ASCII string to Binary bytes:

Formula

wel
Binary('AB')

Output

wel
0x"4142"

Dates and times ​

WEL distinguishes an exact instant from a calendar date or wall-clock time without a time zone. Choosing the correct type helps prevent date shifts across time zones. Refer to Temporal functions for how to work with each type once it's constructed.

DateTime ​

Converts to a DateTime, an exact instant with a time zone.

Use it to record an event happening, such as a creation timestamp, an event time, or an audit record.

wel
DateTime(value)
ParameterDescription
valueA DateTime, an ISO 8601 string, or a map of components. A map of components defaults hour and minute to 0. A String argument must carry an explicit offset or Z. An invalid string raises E020, and an unsupported type raises E100. A map component outside its valid range raises E211.
Convert an ISO 8601 string with a zone

The following example converts an ISO 8601 string with a time zone:

Formula

wel
DateTime('2026-03-15T09:30:00Z')

Output

text
2026-03-15T09:30:00Z

PlainDate ​

Converts to a PlainDate, a calendar date with no time and no zone.

Use it for a date that is the same everywhere, such as an invoice date, a birth date, or a contract start. A DateTime stored in place of a PlainDate can shift a day when it crosses a zone boundary.

wel
PlainDate(value)
ParameterDescription
valueAn ISO 8601 date string, or a value carrying a date. An invalid date, such as a day that doesn't exist in the given month, raises E020.
Convert an ISO 8601 date string

The following example converts an ISO 8601 date string:

Formula

wel
PlainDate('2026-03-15')

Output

text
2026-03-15

PlainTime ​

Converts to a PlainTime, a time of day with no date and no zone, such as a store opening time.

wel
PlainTime(value)
ParameterDescription
valueA time-only string, or a map with hour, minute, and second. An invalid time, such as an out-of-range hour, raises E020.
Convert an ISO 8601 time string

The following example converts an ISO 8601 time string:

Formula

wel
PlainTime('09:30:00')

Output

text
09:30:00

PlainDateTime ​

Converts to a PlainDateTime, a date and time with no zone.

PlainDateTime strips the zone from a DateTime argument rather than converting it, so the wall-clock reading is kept as-is.

wel
PlainDateTime(value)
ParameterDescription
valueA map of components, an ISO 8601 string, or a DateTime. A PlainDate raises E102 because it has no time component to supply. A map component outside its valid range raises E211.
Convert an ISO 8601 date-time string

The following example converts an ISO 8601 date-time string:

Formula

wel
PlainDateTime('2026-03-15T09:30:00')

Output

text
2026-03-15T09:30:00

Duration ​

Converts to a Duration, a length of time written in ISO 8601 duration form. For example, PT1H30M.

wel
Duration(value)
ParameterDescription
valueAn ISO 8601 duration string, a value carrying a duration, or a map of components, such as {hours: 1, minutes: 30}. Duration normalizes negative component values and values above 60. The month and year components must be numbers.
Convert an ISO 8601 duration string

The following example converts an ISO 8601 duration string:

Formula

wel
Duration('PT1H30M')

Output

text
PT1H30M

Sentinels ​

WEL uses the Null() constructor or the Skip sentinel value to represent an absence.

Null ​

Returns null. Takes no arguments.

wel
Null()
Return null

The following example returns null:

Formula

wel
Null()

Output

wel
null

Skip ​

Skip omits a field entirely instead of sending null for it. Refer to Null and Skip for the full comparison, including how Skip filters a list inside map_by. Use Skip when a destination distinguishes an explicitly cleared field from an untouched one, which many CRM APIs do.

wel
Skip

Use case: Convert an inbound payload at the boundary ​

Every field arrives as a string, including ones that logically aren't. Convert them once, at the top, so the rest of the transformation can work in real types:

Input

json
{
  "id": 1001,
  "qty": "3",
  "total": "149.50",
  "shipped": "true",
  "ship_date": "2026-03-15"
}

Formula

wel
{
  order_id: String(_.id),
  qty: Integer(_.qty),
  total: Decimal(_.total),
  shipped: Bool(_.shipped),
  ship_date: PlainDate(_.ship_date)
}

Output

json
{
  "order_id": "1001",
  "qty": 3,
  "total": 149.50,
  "shipped": true,
  "ship_date": "2026-03-15"
}

total keeps its trailing zero because Decimal preserves scale. ship_date is a PlainDate, so it can't drift a day when a later step applies a time zone.

Last updated: