User Tools

Site Tools

You are here: Welcome to PlanetCNC.zone » Expr V4 Language Tutorial » Expression Reference Manual » Built-in Functions
Trace: • Lexical Basics • Built-in Functions

Sidebar

Home


Expressions V4

 Tutorials

 How-To

 Reference

  Lexical basics
  Type system
  Variables and assignment
  Operators
  Expression rules
  Control flow
  Functions
  Built-in functions
   None and NaN
   Arithmetic
   Algebra
   Logarithmic and Exponential
   Trigonometric
   Rounding and Centering
   Strings
   Output, Formatting, Clipboard, and Errors
   Dialog Functions
   Platform and Paths
  Methods and properties
  Built-in methods
   Common Value Methods
   Number Methods
   String Basic Methods
   String Slice Methods
   String Parsing Methods
   String Formatting Methods
   String Regex Methods
   String Trim and Case Methods
  Objects
  Built-in objects
   Global objects
    settings
    controller
    session
    python
   Collections
    array
    map
    bytes
   File Format I/O
    image_data
    image_stream
   Utils
    crypto
    timer
   Comm
    serial
   Dialogs
    file_open
    file_save
    msg_ok
    msg_ok_cancel
    msg_yes_no
    msg_password
   GUI objects
    window
    panel
    group
    splitpanel
    label
    textbutton
    drawablebutton
    togglebutton
    togglegroup
    textinput
    textedit
    numinput
    slider
    combobox
    listbox
    progressbar
    led
    separator
    menu
    image
    snake
  Classes and user-defined objects
  Include system
  Error model
  Execution model and sessions
  Host integration
  Limits and performance
  Formal reference
  Glossary

 Cookbook

exprv4:reference:built_in_functions

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_string()`, 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:

  • 69 regular global functions from the Expr function registry.
  • 32 object constructor functions registered by built-in object types.

Alphabetical Index

`abs`, `acos`, `acosh`, `array`, `asin`, `asinh`, `atan`, `atan2`, `atanh`, `bytes`, `cbrt`, `ceil`, `center`, `centerex`, `clear`, `combobox`, `cos`, `cosh`, `cot`, `crypto`, `csc`, `cube`, `dec`, `deg2rad`, `drawablebutton`, `e`, `enable_print`, `error`, `exp`, `exp10`, `exp2`, `expm1`, `file_open`, `file_save`, `floor`, `from_clipboard`, `group`, `guess_number`, `hypot`, `image`, `image_data`, `image_stream`, `inc`, `label`, `led`, `listbox`, `log`, `log10`, `log1p`, `log2`, `map`, `max`, `menu`, `min`, `msgdlg_ok`, `msgdlg_ok_cancel`, `msgdlg_yes_no`, `msgdlg_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:

  • Argument count is checked by each function.
  • Argument types are checked where required.
  • Arguments are evaluated before the function is called.
  • Built-in boolean helper functions are normal function calls; they do not short-circuit.
  • A user-defined function can shadow a built-in function with the same name.

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.

Numeric 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);

Numeric 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, Clipboard, 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.
`from_clipboard()` string Reads text from the clipboard.
`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.
`to_clipboard(value)` bool-style number Writes text to the clipboard.

Examples: 

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

Dialog Functions

Function Returns Notes
`msgdlg_ok(value, …)` number Shows an OK message dialog and returns the dialog result code.
`msgdlg_ok_cancel(value, …)` number Shows an OK/Cancel message dialog and returns the dialog result code.
`msgdlg_yes_no(value, …)` number Shows a Yes/No message dialog and returns the dialog result code.
`msgdlg_yes_no_cancel(value, …)` number Shows a Yes/No/Cancel message dialog and returns the dialog result code.

Examples: 

msgdlg_ok('Operation complete');
result = msgdlg_ok_cancel('Continue?');

Platform and Paths

Function Returns Notes
`path()` string Returns the current profile path.
`path(relativePath)` string Resolves profile-relative paths that start with `.` and source-relative paths that do not.
`platform()` string Returns `windows`, `linux`, `apple`, `arm`, or `unknown`.

Examples: 

profile = path();
file = path('./scripts/probe.expr');
if (platform() == 'windows')
{
    print('Windows');
}

Data Object Constructors

These functions create general-purpose data objects.

Function Returns Notes
`array(value, …)` array object Creates an array containing the provided values.
`bytes()` bytes object Creates an empty binary byte buffer.
`bytes(size)` bytes object Creates a binary byte buffer 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);
data = bytes(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.
`timer(callback)` timer object Creates a timer object that calls a callable object.

Examples: 

c = crypto();
t = timer(OnTimer);

Comm Object Constructors

Function Returns Notes
`serial()` serial object Creates a serial communication object.

Example: 

port = serial();

File Format I/O 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
`file_open()` file_open object Creates an open-file dialog object.
`file_save()` file_save object Creates a save-file dialog object.

Examples: 

dlg = file_open();
saveDlg = file_save();

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

exprv4/reference/built_in_functions.txt · Last modified: by 127.0.0.1

Page Tools