Table of Contents



Built-in Functions

Built-in functions are global functions provided by Expr and registered by the host application.

This page lists the built-ins available as direct calls, such as `abs(x)`, `print(value)`, and `array(1, 2, 3)`.

This page does not list value methods such as `(123).to_str()`, string methods, array methods, map methods, or GUI object methods. Those are called with member syntax and are documented with methods and objects.

Organization

The built-ins are organized by category, with names sorted alphabetically inside each category.

Use the category sections when learning what is available. Use the alphabetical index when you already know a function name.

The current built-in set contains:

Alphabetical Index

`abs`, `acos`, `acosh`, `array`, `asin`, `asinh`, `atan`, `atan2`, `atanh`, `cbrt`, `ceil`, `center`, `centerex`, `clear`, `combobox`, `cos`, `cosh`, `cot`, `crypto`, `csc`, `cube`, `data_array`, `dec`, `deg2rad`, `drawablebutton`, `e`, `enable_print`, `error`, `exp`, `exp10`, `exp2`, `expm1`, `fileopen`, `filesave`, `floor`, `from_clipboard`, `group`, `guess_number`, `hypot`, `image`, `image_data`, `image_stream`, `inc`, `label`, `led`, `listbox`, `log`, `log10`, `log1p`, `log2`, `map`, `max`, `menu`, `min`, `msg_ok`, `msg_ok_cancel`, `msg_yes_no`, `msg_yes_no_cancel`, `nan`, `none`, `numinput`, `panel`, `path`, `pi`, `platform`, `pow`, `printf`, `print`, `progressbar`, `rad2deg`, `rand`, `round`, `roundup`, `sec`, `separator`, `serial`, `sign`, `sin`, `sinh`, `slider`, `snake`, `splitpanel`, `sprintf`, `sprint`, `sqr`, `sqrt`, `str`, `str_rand`, `str_spaces`, `str_uuid`, `tan`, `tanh`, `textbutton`, `textedit`, `textinput`, `timer`, `to_clipboard`, `togglebutton`, `togglegroup`, `trunc`, `window`.

Call Rules

Built-in functions follow the same call syntax as user-defined functions. 

name(argument1, argument2);

General rules:

When a built-in receives invalid arguments, it raises a runtime error.

None and NaN

Function Returns Notes
`nan()` NaN number Produces a numeric NaN value.
`none()` none Produces the none value.

Examples: 

missing = none();
badNumber = nan();

See also none(), nan(), and errors.

Arithmetic

Function Returns Notes
`abs(x)` number Absolute value.
`dec(value, min, reset)` number Decrements `value`; wraps to `reset` when below `min`. If `value` is `none()` or NaN, returns `reset`.
`inc(value, max, reset)` number Increments `value`; wraps to `reset` when above `max`. If `value` is `none()` or NaN, returns `reset`.
`max(value, …)` number Largest argument. Requires at least one number.
`min(value, …)` number Smallest argument. Requires at least one number.
`rand()` number Random number from 0 to 1.
`rand(max)` number Random integer-style value from 0 to `max`.
`rand(min, max)` number Random integer-style value from `min` to `max`. `min` must be smaller than `max`.
`sign(x)` number `-1`, `0`, or `1` depending on the sign of `x`.

Examples: 

abs(-5);              // 5
max(3, 8, 2);         // 8
index = inc(index, 9, 0);

Algebra

Function Returns Notes
`cbrt(x)` number Cube root.
`cube(x)` number `x * x * x`.
`pow(base, exponent)` number Power function. Negative base with non-integer exponent is not supported.
`sqr(x)` number `x * x`.
`sqrt(x)` number Square root. `x` must be greater than or equal to zero.

Examples: 

sqr(4);               // 16
sqrt(25);             // 5
pow(2, 8);            // 256

Logarithmic and Exponential

Function Returns Notes
`e()` number Euler constant.
`exp(x)` number e raised to `x`.
`exp10(x)` number 10 raised to `x`.
`exp2(x)` number 2 raised to `x`.
`expm1(x)` number `exp(x) - 1`, useful for small `x`.
`log(x)` number Natural logarithm. `x` must be greater than zero.
`log10(x)` number Base-10 logarithm. `x` must be greater than zero.
`log1p(x)` number `log(1 + x)`. `x` must be greater than `-1`.
`log2(x)` number Base-2 logarithm. `x` must be greater than zero.

Examples: 

log(e());             // 1
log10(1000);          // 3
exp2(8);              // 256

Trigonometric

Angles are in radians unless a function name says otherwise.

Function Returns Notes
`acos(x)` number Arc cosine. `x` must be in the range `-1` to `1`.
`acosh(x)` number Inverse hyperbolic cosine. `x` must be greater than or equal to `1`.
`asin(x)` number Arc sine. `x` must be in the range `-1` to `1`.
`asinh(x)` number Inverse hyperbolic sine.
`atan(x)` number Arc tangent.
`atan2(y, x)` number Arc tangent using `y` and `x`. The pair `0, 0` is undefined.
`atanh(x)` number Inverse hyperbolic tangent. `x` must be between `-1` and `1`.
`cos(x)` number Cosine of angle `x`.
`cosh(x)` number Hyperbolic cosine.
`cot(x)` number Cotangent.
`csc(x)` number Cosecant.
`deg2rad(degrees)` number Converts degrees to radians.
`hypot(x, y)` number Length of a 2D vector, equivalent to square root of `x*x + y*y`.
`pi()` number Pi constant.
`rad2deg(radians)` number Converts radians to degrees.
`sec(x)` number Secant.
`sin(x)` number Sine of angle `x`.
`sinh(x)` number Hyperbolic sine.
`tan(x)` number Tangent of angle `x`.
`tanh(x)` number Hyperbolic tangent.

Examples: 

angle = deg2rad(90);
sin(angle);           // 1
rad2deg(pi());        // 180

Rounding and Centering

Function Returns Notes
`ceil(x)` number Rounds up to the next integer.
`center(x, min)` number Dead-zone helper. Returns `0` when absolute `x` is smaller than `min`; otherwise returns `x`.
`centerex(x, min, max, center)` number Advanced centering helper with dead-zone and scaling behavior.
`floor(x)` number Rounds down to the previous integer.
`round(x)` number Rounds to the nearest integer.
`round(x, decimals)` number Rounds to decimal places. Negative `decimals` rounds to powers of ten.
`roundup(x)` number Rounds away from zero.
`trunc(x)` number Truncates fractional part.

Examples: 

round(12.345, 2);     // 12.35
floor(9.8);           // 9
center(0.02, 0.05);   // 0

String Creation

These are global string helpers. String conversion and string inspection are mostly value methods, not global functions.

Function Returns Notes
`str()` string Empty string.
`str(value)` string String representation of `value`.
`str(count, pattern)` string Repeats `pattern` `count` times.
`str_rand(length)` string Random string with the requested length.
`str_spaces(count)` string String containing `count` spaces.
`str_uuid()` string New UUID string.

Examples: 

str(123);             // '123'
str(3, 'ab');         // 'ababab'
str_spaces(4);        // '    '

Output, Formatting, and Errors

Function Returns Notes
`clear()` ok result Clears console output when possible, or sends a clear signal to the active output sink.
`enable_print(enabled)` bool-style number Enables or disables output stream printing for the current context.
`error(value, …)` never returns normally Builds a message from all arguments and raises a user error.
`print(value, …)` ok result Writes all values to output, then writes a newline.
`printf(format, value, …)` ok result Formats with `{}`-style formatting, writes to output, then writes a newline.
`sprint(value, …)` string Builds and returns a string from all arguments.
`sprintf(format, value, …)` string Formats with `{}`-style formatting and returns the result.

Examples: 

print('value=', value);
text = sprintf('X={}, Y={}', x, y);
error('Invalid tool number: ', tool);

Dialogs, Clipboard, Platform, and Paths

Function Returns Notes
`from_clipboard()` string Reads text from the clipboard.
`msg_ok(value, …)` number Shows an OK message dialog and returns the dialog result code.
`msg_ok_cancel(value, …)` number Shows an OK/Cancel message dialog and returns the dialog result code.
`msg_yes_no(value, …)` number Shows a Yes/No message dialog and returns the dialog result code.
`msg_yes_no_cancel(value, …)` number Shows a Yes/No/Cancel message dialog and returns the dialog result code.
`path()` string Returns the current profile path.
`path(relativePath)` string Resolves a path relative to the current include path or source path.
`platform()` string Returns `windows`, `linux`, `apple`, `arm`, or `unknown`.
`to_clipboard(value)` bool-style number Writes text to the clipboard.

Examples: 

profile = path();
file = path('scripts/probe.expr');
to_clipboard('copied text');

Data Object Constructors

These functions create general-purpose data objects.

Function Returns Notes
`array(value, …)` array object Creates an array containing the provided values.
`data_array()` data_array object Creates an empty binary data array.
`data_array(size)` data_array object Creates a binary data array with initial size.
`map(key, value, …)` map object Creates a map. Arguments must be key/value pairs.

Examples: 

items = array('x', 'y', 'z');
lookup = map('x', 10, 'y', 20);
bytes = data_array(256);

Utility Object Constructors

Function Returns Notes
`crypto()` crypto object Creates a crypto helper object.
`guess_number()` guess_number object Creates the guess-number example/game object.
`serial()` serial object Creates a serial communication object.
`timer(callback)` timer object Creates a timer object that calls a callable object.

Examples: 

port = serial();
t = timer(OnTimer);

Image Object Constructors

Function Returns Notes
`image()` image object Creates a GUI image view object.
`image_data()` image_data object Creates an image data object for loading, saving, or holding image data.
`image_stream()` image_stream object Creates an image stream object for sequences or streamed frames.

Examples: 

img = image();
data = image_data();
stream = image_stream();

File Dialog Constructors

Function Returns Notes
`fileopen()` fileopen object Creates an open-file dialog object.
`filesave()` filesave object Creates a save-file dialog object.

Examples: 

dlg = fileopen();
saveDlg = filesave();

GUI Object Constructors

These functions create GUI objects for custom dialogs and forms.

Function Returns Notes
`combobox()` combobox object Combo box control.
`drawablebutton()` drawablebutton object Button with drawable/custom visual behavior.
`group()` group object Group/container control.
`label()` label object Text label control.
`led()` led object LED indicator control.
`listbox()` listbox object List box control.
`menu()` menu object Menu object. Menu items are created through menu methods.
`numinput()` numinput object Numeric input control.
`panel()` panel object Panel/container control.
`progressbar()` progressbar object Progress bar control.
`separator()` separator object Visual separator control.
`slider()` slider object Slider control.
`snake()` snake object Snake game widget.
`splitpanel()` splitpanel object Split panel container.
`textbutton()` textbutton object Text button control.
`textedit()` textedit object Multi-line text edit control.
`textinput()` textinput object Single-line text input control.
`togglebutton()` togglebutton object Toggle button control.
`togglegroup()` togglegroup object Group of toggle buttons.
`window()` window object Top-level custom window/dialog object.

Examples: 

win = window();
p = panel();
b = textbutton();

Methods Are Separate

Object constructors return objects. The object methods are not global functions.

For example, `array()` is a built-in function, but `items.size()` is a method call. 

items = array(1, 2, 3);
items.size();         // method call, not a global built-in function

The same rule applies to string, number, map, GUI, timer, serial, crypto, and image methods.

Common Pitfalls

Expecting Type Conversion Functions

Most type conversions are methods, not global functions. 

value = 123;
text = value.to_string();

Do not look for old global conversion functions in the current language. Use value methods such as `value.to_string()` instead.

Expecting Short-Circuit Boolean Functions

Built-in functions evaluate their arguments before the function is called.

Use operators such as && and || when you need short-circuit evaluation.

Shadowing Built-ins

A user-defined function can shadow a built-in function. 

function abs(value)
{
    return value;
}
 
abs(-5);              // calls the user-defined function

Previous: Functions

Next: Methods and properties