Skip to content

XEG Builtins

The builtin table is closed: these are the only names an expression can call, and a host cannot add one. Every builtin is pure and total, so a wrong argument type yields null rather than an error. This page is generated from spec/expression-reference.json; the grammar and its semantics are on the Expressions page, and the operators on XEG Operators.

Examples evaluate against these bindings unless they name their own, and every one is a conformance case each runtime runs:

{
"hp": 35,
"maxHp": 100,
"name": "Hero",
"alive": true,
"dead": false,
"nothing": null,
"effects": [
"burn",
"slow"
],
"empty": [],
"zero": 0,
"blank": "",
"score": 7,
"label": " padded ",
"player": {
"name": "Hero",
"stats": {
"str": 12,
"dex": 9
}
}
}
abs(x: number): number | null

The absolute value of x.

Returns null when x is not a number; a numeric string is not coerced.

ExpressionResult
abs(-3)3
abs('3')null
round(x: number): number | null

x rounded to the nearest integer, with a half rounding up.

A half always rounds toward positive infinity, matching JavaScript’s Math.round: round(2.5) is 3 and round(-2.5) is -2. It is neither half away from zero nor half to even. Returns null when x is not a number.

ExpressionResult
round(2.5)3
round(-2.5)-2
round(hp / maxHp * 10)4
floor(x: number): number | null

The largest integer less than or equal to x.

Rounds toward negative infinity, so floor(-1.5) is -2. Returns null when x is not a number.

ExpressionResult
floor(1.9)1
floor(-1.5)-2
ceil(x: number): number | null

The smallest integer greater than or equal to x.

Rounds toward positive infinity, so ceil(-1.5) is -1. Returns null when x is not a number.

ExpressionResult
ceil(1.1)2
ceil(-1.5)-1
min(...values: number): number | null

The smallest of one or more numbers.

Takes at least one argument. If any argument is not a number the result is null, rather than the minimum of the ones that are.

ExpressionResult
min(3, 1, 2)1
min(hp, 'x')null
max(...values: number): number | null

The largest of one or more numbers.

Takes at least one argument. If any argument is not a number the result is null, rather than the maximum of the ones that are.

ExpressionResult
max(3, 1, 2)3
max(hp, maxHp)100
clamp(x: number, lo: number, hi: number): number | null

x limited to the range lo to hi, inclusive.

Returns null when any argument is not a number, or when lo is greater than hi; an inverted range is an error, not a swap.

ExpressionResult
clamp(150, 0, 100)100
clamp(-5, 0, 100)0
clamp(5, 10, 0)null
fixed(x: number, digits: number): string | null

x as a string with exactly digits decimal places.

Matches JavaScript’s Number.prototype.toFixed: the exact binary value of x is rounded to digits places, a half rounding away from zero. Because the value is exact, fixed(1.005, 2) is "1.00", since 1.005 is stored just below the half. digits must be an integer from 0 to 20, otherwise the result is null. When the magnitude of x is 1e21 or more the result is str(x).

ExpressionResult
fixed(3.14159, 2)"3.14"
fixed(2, 2)"2.00"
fixed(0.125, 2)"0.13"
fixed(1.005, 2)"1.00"
fixed(hp / 3, 1)"11.7"
upper(s: string): string | null

s converted to uppercase.

Uses Unicode’s default full case mapping, independent of locale, so a character can expand: upper('ß') is "SS". Returns null when s is not a string.

ExpressionResult
upper(name)"HERO"
upper('straße')"STRASSE"
lower(s: string): string | null

s converted to lowercase.

Uses Unicode’s default full case mapping, independent of locale, including the final-sigma rule: a capital sigma at the end of a word lowercases to ς. Returns null when s is not a string.

ExpressionResult
lower(name)"hero"
lower('ΟΔΟΣ')"οδος"
trim(s: string): string | null

s with leading and trailing whitespace removed.

Whitespace is JavaScript’s set: tab, vertical tab, form feed, space, no-break space, U+FEFF, every Unicode space separator, and the line terminators LF, CR, U+2028, and U+2029. U+0085 is not whitespace. Returns null when s is not a string.

ExpressionResult
trim(label)"padded"
trim(3)null
pad(s: string, width: number, fill?: string = " "): string | null

s padded at the start to width UTF-16 code units.

Pads at the start, so numbers align right, like JavaScript’s padStart. fill repeats and is cut to fit, counting code units, and defaults to a space. A string already width long or longer comes back unchanged. width must be an integer from 0 to 4096 and fill a non-empty string, otherwise the result is null.

ExpressionResult
pad('7', 3, '0')"007"
pad('ab', 5, 'xy')"xyxab"
pad(name, 2)"Hero"
slice(s: string, start: number, end?: number): string | null

The UTF-16 code units of s from start up to but not including end.

Matches JavaScript’s String.prototype.slice: a negative index counts from the end, an index past either end is clamped, and a fractional index is truncated toward zero. Omitting end runs to the end of the string. Works on strings only; returns null for anything else.

ExpressionResult
slice('hello', 1, 3)"el"
slice('hello', -3)"llo"
slice(name, 0, 99)"Hero"
len(value: string | array | object): number | null

The size of a string, array, or object.

Counts UTF-16 code units for a string, as JavaScript’s length does, elements for an array, and own keys for an object. Returns null for anything else.

ExpressionResult
len(effects)2
len(name)4
len(player.stats)2
len(hp)null
has(collection: string | array | object, key: any): boolean | null

Whether collection contains key.

Reads as membership: a substring for a string, an element by strict equality for an array, an own key for an object. A non-string key is never found in a string or an object, and an inherited key is never found. Returns null when collection is none of the three.

ExpressionResult
has(effects, 'burn')true
has(name, 'er')true
has(player, 'stats')true
has(hp, 3)null
join(array: array, separator?: string = ","): string | null

The elements of array rendered with str and joined by separator.

separator defaults to a comma. Returns null when array is not an array or separator is not a string.

ExpressionResult
join(effects, ', ')"burn, slow"
join(effects)"burn,slow"
at(collection: string | array, index: number): any

The element or UTF-16 code unit of collection at index.

A negative index counts from the end. An index out of range, a fractional index, or a collection that is neither a string nor an array yields null.

ExpressionResult
at(effects, 0)"burn"
at(effects, -1)"slow"
at(name, 1)"e"
at(effects, 5)null
str(value: any): string

value rendered as a string, exactly as data-bind and interpolation render it.

null renders as the empty string, a boolean as true or false, a number as JavaScript’s String(number) would (shortest round-trip digits, exponent form below 1e-6 and from 1e21 up), an array as its rendered elements joined by commas, and an object as [object Object].

ExpressionResult
str(nothing)""
str(hp)"35"
str(effects)"burn,slow"
str(1e21)"1e+21"
num(value: any): number | null

value converted to a number.

A number passes through, true is 1 and false is 0, and a string is converted as JavaScript’s Number(string) converts it: trimmed, then read as a decimal literal (an optional sign, digits with an optional decimal point, an optional exponent) or an unsigned 0x, 0o, or 0b integer. An empty string, Infinity, a value too large for a double, and anything JavaScript reads as NaN yield null.

ExpressionResult
num(' 42 ')42
num('1.5e3')1500
num(alive)1
num('0x10')16
num('1_000')null
bool(value: any): boolean

Whether value is truthy.

null, false, 0, and the empty string are falsy. Everything else is truthy, including an empty array and an empty object.

ExpressionResult
bool(zero)false
bool(empty)true
bool(blank)false