yoshida yoshida
Open the editor

Docs Format Expressions

Expressions: Functions

On this page

A function is called by its name, with its arguments in parentheses: round(price, 1). Arguments and results have types; there is no conversion between them. Calling an unknown function is error 3002 (with a "did you mean" hint). A wrong number of arguments or a wrong argument type is error 3003.

The functions are grouped by what they work on. The table below lists every group; the existing functions are described on this page, and the others on the pages linked from the table.

GroupFunctionsPage
Existingmin max clamp abs floor ceil round len upper lower trim fmt avg_color mix with_alpha rgb rgba matchthis page
Numbers and trigonometrysqrt pow sign sin cos tan asin acos atan2 deg rad lerp remap wrapNumbers
Textcontains starts_with ends_with replace slice pad_start repeat title_case roman partText
Listshas get index_of sum avg min max count join lastLists
Dates and timesdate_fmt year month day weekday hour minute add_days add_hours days_betweenDates and times
Colorshsl hsla lighten darken luminance readableColors and random
Randomrand rand_int pickColors and random

Existing functions

FunctionSignatureNotes
min, max(number, number, ...) -> numberAny number of arguments. When the first argument is a list, see Lists
clamp(value, lo, hi) -> numberThe middle of the three values; the CSS order clamp(lo, value, hi) also works. With lo above hi it is not an error and still gives the middle value: clamp(10, 5, 0) is 5
abs, floor, ceil(number) -> number
round(number, digits = 0) -> numberHalves away from zero, on the decimal digits: round(1.005, 2) is 1.01. digits may be negative: round(1234.5, -2) is 1200. digits is rounded to a whole number and limited to -15 to 15
len(list or text) -> numberItems in a list, characters in text
upper, lower, trim(text) -> textSee below for upper and lower
fmt(number, decimals) -> textfmt(0.5, 2) is 0.50. Rounds as round does, and never prints -0.00. decimals is rounded to a whole number and kept between 0 and 15
avg_color(image) -> colorAverage of the opaque pixels of an image param
mix(color, color, t) -> colorLinear blend, t from 0 to 1
with_alpha(color, a) -> colora from 0 (transparent) to 1
rgb, rgba(r, g, b[, a]) -> colorChannels 0 to 255, a from 0 to 1, stored on the 8-bit grid: rgba(255, 0, 0, 0.5) is #FF000080
match(value, key, result, ..., default) -> result typeResult of the first key equal to value, else default. See below

upper and lower change the case of letters in the ASCII, Latin-1 Supplement, Latin Extended-A, Greek and Cyrillic blocks. Other characters are unchanged, and so is ß: upper('ß') is ß.

Names of functions and other names

A bare name never calls a function, and a call always has parentheses. So a param, constant, loop name or function argument may use the name of a built-in function. min as a param is a value, and min(a, b) still calls the built-in.

A design function may also use a built-in's name, such as round. Inside that design the design function replaces the built-in: later calls to round(...) run the design's function, and the design gets warning 1113. The function's own body still sees the built-in, so a wrapper can call it (see Constants and functions). Other designs are not affected.

Reserved words (canvas, render, card, true, false, and, or, not, in) cannot be used for any name (error 1106).

A design can add its own functions, such as tile_x(i), and named constants: see Constants and functions.

Choosing between several values

match gives the result of the first key equal to the value, and in tests whether a value equals one item of a list. Both replace long chains of == tests. Keys have the value's type, and all results and the default share one type. Only the chosen result is evaluated, as with ? :.

Membership, with in in place of or.

Before:

"has_n": "k == 'back' or k == 'forward' or k == 'shortcut'"

After:

"has_n": "k in ['back', 'forward', 'shortcut']"

A value picked by key, with match in place of a ? : chain.

Before:

"kind_color": "k == 'start' ? c_start : k == 'finish' ? c_finish : k == 'safe' ? c_safe : c_plain"

After:

"kind_color": "match(k, 'start', c_start, 'finish', c_finish, 'safe', c_safe, c_plain)"

Which pips of a die face are shown, with one match in place of six comparisons.

Before:

"pip": "face == 1 ? k == 4 : face == 2 ? (k == 0 or k == 8) : face == 3 ? (k == 0 or k == 4 or k == 8) : face == 4 ? (k == 0 or k == 2 or k == 6 or k == 8) : face == 5 ? (k == 0 or k == 2 or k == 4 or k == 6 or k == 8) : (k == 0 or k == 2 or k == 3 or k == 5 or k == 6 or k == 8)"

After:

"pip": "match(face, 1, k in [4], 2, k in [0, 8], 3, k in [0, 4, 8], 4, k in [0, 2, 6, 8], 5, k in [0, 2, 4, 6, 8], k in [0, 2, 3, 5, 6, 8])"

Examples

"text": "{upper(title)}"
"text": "{fmt(price, 2)} €"
"fill": "mix(accent, #FFFFFF, 0.85)"
"color": "with_alpha(accent, 0.6)"
"fill": "rgb(30, 30, 40)"
"fill": "rgba(0, 0, 0, 0.5)"
"w": "min(80%, len(title) * 40)"
"size": "round(base * 1.5)"
"fill": "mix(avg_color(art), #000000, 0.4)"

avg_color(art) needs an image param (or an image-typed value) as its argument, and the image has to load, so it follows the same rules as an image layer for missing files.

The editor shows each function's signature, description and an example as you type; see Builder: Expression editor.

↑↓ to moveEnter to openEsc to close