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 } }}- Numeric:
abs,round,floor,ceil,min,max,clamp,fixed - String:
upper,lower,trim,pad,slice - Collection:
len,has,join,at - Coercion:
str,num,bool
Numeric
Section titled “Numeric”abs(x: number): number | nullThe absolute value of x.
Returns null when x is not a number; a numeric string is not coerced.
| Expression | Result |
|---|---|
abs(-3) | 3 |
abs('3') | null |
round(x: number): number | nullx 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.
| Expression | Result |
|---|---|
round(2.5) | 3 |
round(-2.5) | -2 |
round(hp / maxHp * 10) | 4 |
floor(x: number): number | nullThe 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.
| Expression | Result |
|---|---|
floor(1.9) | 1 |
floor(-1.5) | -2 |
ceil(x: number): number | nullThe 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.
| Expression | Result |
|---|---|
ceil(1.1) | 2 |
ceil(-1.5) | -1 |
min(...values: number): number | nullThe 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.
| Expression | Result |
|---|---|
min(3, 1, 2) | 1 |
min(hp, 'x') | null |
max(...values: number): number | nullThe 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.
| Expression | Result |
|---|---|
max(3, 1, 2) | 3 |
max(hp, maxHp) | 100 |
clamp(x: number, lo: number, hi: number): number | nullx 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.
| Expression | Result |
|---|---|
clamp(150, 0, 100) | 100 |
clamp(-5, 0, 100) | 0 |
clamp(5, 10, 0) | null |
fixed(x: number, digits: number): string | nullx 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).
| Expression | Result |
|---|---|
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" |
String
Section titled “String”upper(s: string): string | nulls 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.
| Expression | Result |
|---|---|
upper(name) | "HERO" |
upper('straße') | "STRASSE" |
lower(s: string): string | nulls 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.
| Expression | Result |
|---|---|
lower(name) | "hero" |
lower('ΟΔΟΣ') | "οδος" |
trim(s: string): string | nulls 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.
| Expression | Result |
|---|---|
trim(label) | "padded" |
trim(3) | null |
pad(s: string, width: number, fill?: string = " "): string | nulls 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.
| Expression | Result |
|---|---|
pad('7', 3, '0') | "007" |
pad('ab', 5, 'xy') | "xyxab" |
pad(name, 2) | "Hero" |
slice(s: string, start: number, end?: number): string | nullThe 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.
| Expression | Result |
|---|---|
slice('hello', 1, 3) | "el" |
slice('hello', -3) | "llo" |
slice(name, 0, 99) | "Hero" |
Collection
Section titled “Collection”len(value: string | array | object): number | nullThe 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.
| Expression | Result |
|---|---|
len(effects) | 2 |
len(name) | 4 |
len(player.stats) | 2 |
len(hp) | null |
has(collection: string | array | object, key: any): boolean | nullWhether 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.
| Expression | Result |
|---|---|
has(effects, 'burn') | true |
has(name, 'er') | true |
has(player, 'stats') | true |
has(hp, 3) | null |
join(array: array, separator?: string = ","): string | nullThe 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.
| Expression | Result |
|---|---|
join(effects, ', ') | "burn, slow" |
join(effects) | "burn,slow" |
at(collection: string | array, index: number): anyThe 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.
| Expression | Result |
|---|---|
at(effects, 0) | "burn" |
at(effects, -1) | "slow" |
at(name, 1) | "e" |
at(effects, 5) | null |
Coercion
Section titled “Coercion”str(value: any): stringvalue 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].
| Expression | Result |
|---|---|
str(nothing) | "" |
str(hp) | "35" |
str(effects) | "burn,slow" |
str(1e21) | "1e+21" |
num(value: any): number | nullvalue 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.
| Expression | Result |
|---|---|
num(' 42 ') | 42 |
num('1.5e3') | 1500 |
num(alive) | 1 |
num('0x10') | 16 |
num('1_000') | null |
bool(value: any): booleanWhether value is truthy.
null, false, 0, and the empty string are falsy. Everything else is truthy, including an empty array and an empty object.
| Expression | Result |
|---|---|
bool(zero) | false |
bool(empty) | true |
bool(blank) | false |