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.
Integer(value)| Parameter | Description |
|---|---|
| value | An 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
Integer('42')Output
42Pass through an existing integer
The following example passes an existing Integer through unchanged:
Formula
Integer(42)Output
42Decimal
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.
Decimal(value)| Parameter | Description |
|---|---|
| value | A 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
Decimal('19.99')Output
19.99Convert an integer to a Decimal
The following example converts an integer to a Decimal:
Formula
Decimal(5)Output
5Float
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.
Float(value)| Parameter | Description |
|---|---|
| value | A 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
Float('3.14')Output
3.14Parse 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.
parse_integer(input, options)| Parameter | Description |
|---|---|
| input | A string of digits. Malformed text, a decimal place, or an exponent raises E225. A non-string argument raises E100. |
| options | An optional map to control how input parses.
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
parse_integer('000030')Output
30Convert digit-grouped text
The following example converts text grouped with a thousands separator:
Formula
parse_integer('1,000,000', {thousands_separator: ','})Output
1000000Convert a hexadecimal string
The following example converts a hexadecimal string:
Formula
parse_integer('ff', {base: 16})Output
255parse_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.
parse_decimal(input, options)| Parameter | Description |
|---|---|
| input | A numeric string. parse_decimal also accepts .5, 1., and 1e3. Malformed text, NaN, or infinity raises E225. A non-string argument raises E100. |
| options | An optional map to control how input parses.
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
parse_decimal('00012.50')Output
12.50Convert 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
parse_decimal('1.234,56', {decimal_separator: ',', thousands_separator: '.'})Output
1234.56parse_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.
parse_float(input, options)| Parameter | Description |
|---|---|
| input | A 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. |
| options | An optional map to control how input parses.
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
parse_float('12.50')Output
12.5Convert a value too small for a Float
The following example converts a value too small for a Float, which rounds to zero:
Formula
parse_float('1e-400')Output
0Text 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.
String(value)| Parameter | Description |
|---|---|
| value | A scalar value. |
Convert an integer to a string
The following example converts an integer to a string:
Formula
String(42)Output
42Convert a Decimal to a string
The following example converts a Decimal to a string:
Formula
String(Decimal('19.99'))Output
19.99Bool
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:
if _.flag == 'Y' then true else falseBool(value)| Parameter | Description |
|---|---|
| value | A Boolean, or the string 'true' or 'false'. |
Convert the string 'true'
The following example converts the string 'true' to a Boolean:
Formula
Bool('true')Output
trueBinary
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.
Binary(value)| Parameter | Description |
|---|---|
| value | An 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
Binary('AB')Output
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.
DateTime(value)| Parameter | Description |
|---|---|
| value | A 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
DateTime('2026-03-15T09:30:00Z')Output
2026-03-15T09:30:00ZPlainDate
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.
PlainDate(value)| Parameter | Description |
|---|---|
| value | An 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
PlainDate('2026-03-15')Output
2026-03-15PlainTime
Converts to a PlainTime, a time of day with no date and no zone, such as a store opening time.
PlainTime(value)| Parameter | Description |
|---|---|
| value | A 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
PlainTime('09:30:00')Output
09:30:00PlainDateTime
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.
PlainDateTime(value)| Parameter | Description |
|---|---|
| value | A 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
PlainDateTime('2026-03-15T09:30:00')Output
2026-03-15T09:30:00Duration
Converts to a Duration, a length of time written in ISO 8601 duration form. For example, PT1H30M.
Duration(value)| Parameter | Description |
|---|---|
| value | An 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
Duration('PT1H30M')Output
PT1H30MSentinels
WEL uses the Null() constructor or the Skip sentinel value to represent an absence.
Null
Returns null. Takes no arguments.
Null()Return null
The following example returns null:
Formula
Null()Output
nullSkip
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.
SkipUse 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
{
"id": 1001,
"qty": "3",
"total": "149.50",
"shipped": "true",
"ship_date": "2026-03-15"
}Formula
{
order_id: String(_.id),
qty: Integer(_.qty),
total: Decimal(_.total),
shipped: Bool(_.shipped),
ship_date: PlainDate(_.ship_date)
}Output
{
"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.
Related
- Data types: The 16 WEL data types and when to use each one.
- Numeric functions: Round a
Decimal. - Temporal functions: Work with dates after conversion.
- Error codes: Troubleshoot job failures such as
E008,E020,E100,E102,E211,E218, andE225.
Last updated: