Roomle Script Language Reference

This document provides a reference for the RoomleScript language, which is contained in the values of the Roomle Component Definition JSON objects and is a proprietary language for scripts interpreted by the Rubens Configurator core.

RoomleScript's syntax is loosely based on the JavaScript language and provides extensive possibilities to use in the component definitions.

Variables

Variables are declared automatically without any keywords. Type is also assigned automatically and there is no type declaration. To undeclare/delete a variable, which is not a parameter, you can use the function. Functions and can be checked if a variable is declared.

WARNING If a variable is accessed before the declaration, it will be interpreted as a String.

Variables can also be declared in the connection, other and other_connection contexts.

Parameters and superseded parameters are accessible by their key attribute in the same way as a variable.

The scope of variables is different for different scripts. See for details.

Example:

• Declare a variable:

width = 500; /* width is declared and initialized to value  500 */

• Undeclare a variable:

setnull(width); /* width is deleted */
if (isnull(width)) {
  /* isnull is true after width has been set to null */
  /* do something */
}

• Check if components on both sides of the connection have a width declared and store information about it in this component:

self.widthDeclaredOnBothSides = !isnull(self.width) && !isnull(other.width);

• Store indices i and j in the current connection (i.e. in a docking point of a docking range):

connection.i = xFromVector(connection.position) / 200;
connection.j = zFromVector(connection.position) / 200;

• Work with the index from the other side of the connection:

if (!isnull(other_connection.i)) {
  /* do something */
}

Data Types

Data types are assigned automatically. All types are value types, there are no reference types in RoomleScript, which is in conformity with the basic concept of the component update process.

Example:

arr1 = [10, 20];
arr2 = arr1; /* no reference types => makes copy or arr1 */
pushBack(arr1, 30); /* arr1 is [10, 20, 30] */
pushBack(arr2, 40); /* arr2 is [10, 20, 40] */

Boolean

Values are true and false. These are internally handled as integers with values 1 and 0.

Example:

• Boolean variables

isRoot = true;
if (isRoot) {
  /* ... */
}

hasRightArmrest = in(elementType, 'sofa', 'armchair', 'inlinearmrest_right', 'longchair_right');

• using advantage of internal data type

totalWidth =
  hasLeftArmrest * armrestWidth + width + hasRightArmrest * armrestWidth;
/* which is the same as */
totalWidth =
  (hasLeftArmrest ? armrestWidth : 0) +
  width +
  (hasRightArmrest ? armrestWidth : 0);

Integer

New in 2023: In order to keep values stored in Integer type parameters as integers or for defining an integer as an internal value, you can use i suffix for numeric literals to force them as integers. Example:

{
    "id": "minexamples:integers",
    "label": "
        label = 'Float literal: ' | 100 | ' Integer literal: ' | 100i;
        // prints: Float literal: 100.00 Integer literal: 100
    ",
    "parameters": [
        {
            "key": "intConst",
            "type": "Integer",
            "defaultValue": 10,
            "label": "
                'intConst: ' | intConst
                // prints: intConst: 10
            ",
            "visible": true
        },
        {
            "key": "fltConst",
            "type": "Decimal",
            "defaultValue": 10,
            "label": "
                'fltConst: ' | fltConst
                // prints: fltConst: 10.00
            ",
            "visible": true
        }
    ]
}

float (data type)

Floats are internally handled as single precision floating point numbers (32 bits) and are precise up to about 7 digits.

Any number is considered to be a float by default, unless it has an i suffix (i.e. 100i) or comes from a parameter, which type is Integer.

You can use equality operation on floats safely up to three decimal spaces.

Example:

1.122 * 2 == 2.244; /* evaluates as true */
1.122 * 2 == 2.245; /* evaluates as false */
/* warning: following are not guaranteed to be precise */
1.12233 * 2 == 2.24466; /* evaluates as true */
1.1224 * 2 == 2.2447; /* evaluates as true (!) */
1.1223 * 2 == 2.2447; /* evaluates as false (!) */

String

Strings can be delimited by single ' or double " quotes. However, as the scripts in the JSON files are also delimited with double quotes, those must be escaped \".

It is highly recommended to use single quote delimited strings as the primary choice for obvious reasons.

Arrays

RoomleScript currently newly supports array of all data types. The type of array is determined by the strongest datatype stored inside at the time of initialization. Strength of data types is ascending as follows: boolean, integer, float, string.

You can insert a weaker datatype to an array, but you can not insert a value that has a stronger datatype than the array.

Array initialization:

arr1 = []; /* empty array */
arr2 = [10, 20]; /* array of consts */
offset1 = 100;
offset2 = 150;
offset3 = 200;
arr3 = [
  offset1,
  offset2,
  offset3,
]; /* arrays initialized by variables by values (not by reference) */
offset1 = 200; /* arr3 stays [100, 150, 200] */

Vector2f

Usage:

v = Vector2f{100, 200};

Vector3f

Keywords

if - else if - else

Usage:

if (condition1) {
  /* ... */
} else if (condition2) {
  /* ... */
} else {
  /* ... */
}

for

Standard for loop. If script in which the loop is used has a write access, it is recommended to use the local _ scope prefix.

Usage:

for (_.i = 0; _.i < iterations; _.i++) {
  /* ... */
}

break

Useful in the for loop to immediately exit the current loop.

Usage:

for (_.i = 0; _.i < 100; _.i = _.i + 1) {
  if (_.i == 20) {
    break;
  }
}

continue

Useful in the for loop to immediately skip to the next iteration.

Usage:

for (_.i = 0; _.i < length(arr); _.i++) {
  _.v = get(arr, _.i);
  if (_.v == 0) {
    continue;
  }
  pushBack(arr2, _.v);
  countValid++;
}

return

Immediately terminates execution of the current script. If script has an internal value to store the result (like label or condition), you can use return to assign to it.

Usage:

• In a condition script

condition = true;
if (connection.isPreview && !frontSideIsVisible) {
  return false; /* assigns to `condition` and terminates script */
}

• In the numberInPartList script

if (hasWalls) {
  return wallsCount; /* assigns to `number` and terminates script */
} else {
  number = 0; /* assigns to `number` */
  return; /* terminates script */
}

• In any script

if (allDone) {
  return; /* terminate immediately */
}
/* or continue doing something */

Operators

Comments

Single line comments

Single line comments can start with // or #.

// this is a single line comment
# this is a single line comment as well

WARNING Using single line comments tends to break components while side loading from local drive for testing. For this reason, // style comments are converted to /* */ style comments by the Roomle Component Tool / roomle-content-tool-api format function.

Multi-line comments

/* 
this is a 
multiline comment 
*/

Scope and Context of Variables

The default scope of any internal variable or parameter is the whole current component. Some scripts have read/write access to the component data, some scripts only have read access. To find out which scripts can access which context, you can refer to the [Script Access Rights] chapter.

RoomleScript also provides contexts on several occasions. This is an overview of them:

Internal values

Some scripts have internal values defined. See the table and their purpose:

Functions

As of beginning of 2024, RoomleScript has a possibility to declare custom functions. As of Q2 2024, component scoped functions are provided.

Every function in RoomleScript is executed in the context of the script from which the function has been called. Therefore, functions can get or set values with the same rights as the script from which the function has been called. If a variable or a parameter exists and gets assigned in the scope of the function, its value is overwritten. Based on the access rights of the script, the variable is either changed for the current script only or for the whole component (the self context). If the script doesn't have write access rights, the parameter or variable get shadowed with a local variable. If no parameter or no variable in the scope of the function exists and there is an assignment to a new variable, it will be declared as an internal varaible of the function.

Function's parameters are always declared for the function and should not shadow variables or parameters in the scope where the function resides (be it a component.function or local function). A warning will be thrown if this is the case.

Functions can be nested (functions called within other functions), but can not be recursive (function calls the itself directly or indirectly).

Recommendation: Always use the context when working with function. Always use _. or self. prefixes inside the functions. This will avoid errors caused by suddenly adding a conflicting variable in the future. Let only the function's parameters stay without the context.

Component Functions

Functions can be declared in the component.functions array. Such functions are then declared for the whole component and accessible based on their type attribute. Based on core-provided functions or contexts in the function, either of the four types have to be specified. Complex functionality can be defined for the component, which can save a lot of repeating code and related coding problems and also enables an API-like design approach to component creation.

{
    "id": "example:function",
    "functions": [
        {
            "key": "SumOfTwoNumbers",
            "type": "default",
            "arguments": [
                {
                    "key": "a"
                },
                {
                    "key": "h"
                }
            ],
            "script": "return a + b;"
        }
    ],
    "onUpdate": "
        self.x = SumOfTwoNumbers(100, 200);
    "
}

The attributes of a function object are:

• key The identifier of the function that will be used for calling it.

• type

  • default if not set, this is the default value. Useful for functions that do general computations.

  • geometry Required for functions containing geometry objects calls, like AddCube function

  • changeable Supports setBoxForMeasurement, setVisible, setEnabled

  • onUpdate Supports requestDockItem and changeable functions

  • collisionCondition For accessing the collisionCondition functions are getters that are available in the connection.collisionCondition script: getBoxOrigin, getBoxSize, getBoxForMeasurementOrigin, getBoxForMeasurementSize

• arguments Array of function parameters:

  • key The key to access the argument inside the function

  • defaultValue If set, the argument is non-mandatory in the function call (the defaultValue is used instead) and also allows using a keyword argument.

• script The body of the function. The keyword return terminates the function and if a value follows, it is returned.

Following function Sum can be called with any amount of arguments up until 5, i.e. Sum(1, 2) or Sum(1, 2, 3, 4, 5).

{
    "key": "Sum",
    "type": "default",
    "arguments": [
        {
            "key": "num0",
            "defaultValue": 0
        },
        {
            "key": "num1",
            "defaultValue": 0
        },
        {
            "key": "num2",
            "defaultValue": 0
        },
        {
            "key": "num3",
            "defaultValue": 0
        },
        {
            "key": "num4",
            "defaultValue": 0
        }
    ],
    "script": "
        return num0 + num1 + num2 + num3 + num4;
    "
}

Following function call uses the keyword arguments:

{
    "id": "tests:componentfunctions",
    "functions": [
        {
            "key": "AddBoardWithHole",
            "type": "geometry",
            "arguments": [
                {
                    "key": "cubeSize"
                },
                {
                    "key": "cubeColor",
                    "defaultValue": "isdt:wood_oak"
                },
                {
                    "key": "holeDiameter",
                    "defaultValue": 100
                },
                {
                    "key": "holeColor",
                    "defaultValue": "testing101:mr_chipboard"
                }
            ],
            "script": "
                _.w = cubeSize;
                _.h = 30;
                _.d = cubeSize / 2;
                AddCube(Vector3f{_.w, _.d, _.h});
                 SetObjSurface(cubeColor);

                if (holeDiameter < _.d) {
                    _.r = holeDiameter / 2;
                    AddCylinder(_.r, _.r, 2 * _.h, 16);
                     MoveMatrixBy(Vector3f{_.w / 2, _.d / 2, 0});
                     SetObjSurface(holeColor);
                    MinusOperator();
                }
            "
        },
        {
            "key": "Array_Sum",
            "type": "default",
            "arguments": [
                {
                    "key": "array"
                }
            ],
            "script": "
                _.sum = 0;
                for (_.i = 0; _.i < length(array); _.i = _.i + 1) {
                    _.sum = _.sum + get(array, _.i);
                }
                return _.sum;
            "
        }
    ],
    "onUpdate": "
        self.sum = Array_Sum([100, 400, 500]);
    ",
    "geometry": "
        AddBoardWithHole(self.sum, 'isdt:black', 400, 'isdt:white');

        AddBoardWithHole(self.sum);
         MoveMatrixBy(Vector3f{self.sum, 0, 0});

        AddBoardWithHole(self.sum, holeColor = 'isdt:yellow'); // keep cubeColor and holeDiameter default, set holeColor
         MoveMatrixBy(Vector3f{2 * self.sum, 0, 0});
    "
}

SubComponent Functions

If component.functions are defined, they can be accessible in the subComponent. Keep in mind, that the functions are evaluated not in the subComponent, but in the current component, as if they were just copied to the current component's functions array. In this case, the functions should be prefixed with the subComponent's internalId. See following example where the functions are referred and used by another component.

{
    "id": "tests:subcomponentfunctions",
    "subComponents": [
        {
            "internalId": "Functions",
            "componentId": "tests:subcomponentfunctions",
            "active": false
        }
    ],
    "onUpdate": "
        self.sum = Functions.Array_Sum([100, 400, 500]);
    ",
    "geometry": "
        Functions.AddBoardWithHole(self.sum, 'isdt:black', 400, 'isdt:white');

        Functions.AddBoardWithHole(self.sum);
         MoveMatrixBy(Vector3f{self.sum, 0, 0});

        Functions.AddBoardWithHole(self.sum, holeColor = 'isdt:yellow');
         MoveMatrixBy(Vector3f{2 * self.sum, 0, 0});
    "
}

Notice, that the subComponent is not active. If a subComponent only carries functions or data and is not expected to be a part list entry or a geometry subComponent, there is no point for it to remain active.

Such feature allows you to create a component with a library of functions that can be linked to other components.

However, if the functions in the subComponent are nested, they need to be called in the correct context, which is a complication and will be solved with a feature in the future.

Custom Local Functions

Local functions can be defined using the function keyword, very similarly as it is done in JavaScript. Local functions are valid only in the script where they are declared and all calls of it must be done behind its declaration.

Examples:

x = getFive(); // error, function is used before its declaration

function getFive() {
  return 5;
}

y = getFive(); //

{
    "onUpdate": "
        function add(a, b) {
            return a + b;
        }
    ",
    "geometry": "
        AddCube({add(2 + 3) * 100, 100, 100}); // error - function add is not declared in the geometry script
    "
}

{
    "id": "tests:functions",
    "parameters": [
        {
            "key": "num",
            "type": "Integer",
            "visible": true,
            "validValues": [
                1,
                2,
                5
            ]
        }
    ],
    "onUpdate": "
        function setNum(n) {
            self.num = n;
        }
        setNum(2); // will set the parameter num to 2
    ",
    "geometry": "
        AddCube({self.num * 1000, 1000, 1000}); // result: 2000, 1000, 1000

        function setNum(n) { // function declarations will not conflict since they are local; this is, however, not a good practice
            self.num = n;
        }
        setNum(5); // will not set the parameter num to 5, instead will create a internal variable in the geometry script under the identifier num which shadows the parameter from that place on

        AddCube({self.num * 1000, 1000, 1000}); // result: 5000, 1000, 1000
         MoveMatrixBy({0, 1000, 0});
    "
}

Constants

Convert degrees to radians: a * M_PI / 180

Convert radians to degrees: a * 180 / M_PI

Available Functions

List of available functions in all RoomleScripts of the component definition.

acos

(a: float) : float

Arcus cosine (arccosine)

Parameters:

• a: float value between -1 and 1

Returns: arccosine of a in radians.

Usage:

v = 0.5;
angleRad = acos(v); /* returns 1.04719755 */
angle = (angleRad / M_PI) * 180; /* 60 */

activeGroupInView

() : String

Queries the configurator UI to get the currently selected parameter group. This is useful for manipulating geometry based on what the user is configuring.

⚠️ Warning: This function can query the open group into a variable which can be used in the whole component. This is dangeours and can cause serious errors, because it is possible to change configuration based on the user interaction. The values retrieved by this function should only be used in the geometry script to change the view to hide walls, open doors etc. or to remove certain docking previews in the parentDocking condition if used together with the connection.isPreview getter.

Returns: key property of the current parameter group

Usage:

• geometry:

_.displayOpenDoor = activeGroupInView() === 'grpInternalEquipment';

AddCube(Vectorf3{doowWidth, doorThickness, doorHeight});
if (_.displayOpenDoor) {
    /* rotate the door to visualize it is open */
    RotateMatrixBy(Vector3f{0, 0, 1}, Vector3f{0, 0, 0}, 105);
}

• parent docking condition:

if (connection.isPreview) {
    _.showPreviewOnOuterWall = activeGroupInView() !== 'grpInternalEquipment');
    if (!_.showPreviewOnOuterWall) {
        return false;
    }
}

asin

(a: float) : float

Arcus sine (arcsine)

Parameters:

• a: value between -1 and 1

Returns: arcsine of a in radians.

Usage:

v = 0.5;
angleRad = asin(v); /* returns 523598776 */
angle = (angleRad / M_PI) * 180; /* 30 */

atan

(a: float) : float

Arcus tangent.

Parameters:

• a: value between -1 and 1

Returns: arctangent of a in radians.

atan2

(y: float, x: float) : float

Arcus tangent defined by ratio of opposite and adjacent side of the triangle.

Parameters:

• y: length of opposite side

• x: length of adjacent side

Returns: arctangent of the angle in radians.

ceil

(number: float, digits: float) : float

Nearest higher value

Parameters:

• number: the number to be ceiled

• digits: count of decimal digits

Returns: Nearest higher value rounded to given amount of decimal spaces.

Usage:

x = 123.4567;
ceil(x, 0); /* returns 124 */
ceil(x, 2); /* returns 123.46 */

cos

(valueRad: float) : float

Cosine

Parameters:

• valueRad: value in radians

Returns: cosine value of a.

cosh

(valueRad: float) : float

Hyperbolic cosine

Parameters:

• valueRad: value in radians

Returns: hyperbolic cosine value of a.

exp

(x: float) : float

Exponential function

Parameters:

• x: the exponent

Returns: Value of e powered to x

fabs

(x: float) : float

Absolute value

Parameters:

• x: value

Returns: x if x is positive or -x if x is negative.

Usage:

fabs(5); /* returns 5 */
fabs(-5); /* returns 5 */

float

(value: any) : float

Convert to float

Parameters:

• value the value to try to convert to float

Returns: If value starts with number, returns the first parsed number, otherwise 0.

Usage:

float('5'); /* returns 5.0 */
float('5 hello 3432'); /* returns 5.0 */
float('5.3'); /* returns 5.3 */
float('5,3'); /* returns 5.0 */
float(' 5'); /* returns 5.0 */
float('_5'); /* returns 0.0 */
float([5]); /* returns 0.0 */
float([1]); /* returns 0.0 */
float(Vector3f{5,5,5}) /* returns 0.0 */

floor

(number: float, digits: float) : float

Nearest lower value

Parameters:

• number: the number to be floored

• digits: count of decimal digits

Returns: Nearest lower value rounded to given amount of decimal spaces.

Usage:

x = 123.4567;
floor(x, 0); /* returns 123 */
floor(x, 2); /* returns 123.45 */

fmod

(dividend: float, divisor: float) : float

Floating point modulo

Parameters:

• dividend: float

• divisor: float

Returns: Modulo as float.

Warning Works well only with integers that can be represented by single precision floating point numbers (32 bits, up to around 7 digits).

Usage:

fmod(13, 4); /* returns 1 */
fmod(12, 4); /* returns 0 */
fmod(123456789, 1234567); /* will not work well */

get

(array: [float], index: Integer) : float

Reads an array element at a given index.

Parameters:

• array: the array you want to access

• index: index of the element in the array, index of the first element is zero 0

  • ⚠️ float indices will floor to the next lower integer

Returns: The number from the array at the given index or 0 if fails.

Throws:

• [1404] Index out of bounds. Returns 0 in this case, execution continues

Usage:

arr = [10, 20, 30, 40];
get(arr, 2); /* returns 30 */
get(arr, 2.9); /* returns 20 */
get(arr, 2.999999); /* returns 20 */
get(
  arr,
  2.9999999
); /* returns 30 (floating point precision flips to index 3) */
get(arr, 5); /* returns 0, throws 1404 */
get(arr, -1); /* returns 0, throws 1404 */

getComponentProperty

(propertyKey: 'runtimeId' | 'externalId' | 'catalogId', runtimeId*: integer) : integer | string

Returns the unique runtime id, or component Id of the current component. If this function is used in a collisionCondition script, such a property of another colliding component can be retrieved.

Note: parts of an ID are catalogId:externalId

Parameters:

• propertyKey either runtimeId, externalId or catalogId string values

• runtimeId a runtime ID of a different component, only availabe in the collisionCondition

Returns:

• unique runtime ID as an integer

• external or catalog ID as a string

Usage:

id = getComponentProperty('runtimeId'); // equivalent to getUniqueRuntimeId()
componentId =
  getComponentProperty('catalogId') | ':' | getComponentProperty('externalId');

"collisionCondition": "
    for (i = 0; i < length(collidingComponentIDs); i++) {
        collidingComponentId = get(collidingComponentIDs, i);
        // avoid collision with the catalog:shelf component
        if (getComponentProperty('externalId', collidingComponentId) == 'shelf') {
            return false;
        }
    }
    return true;
"

getDockPosition

() : Vector3f

Get position of child docking point in the coordinate system of the parent.

Returns: Vector from parent origin to child docking point or zero Vector3f if component is the root component.

getDockPositionRelativeToParentDock

() : Vector3f

Get position of the child docking point in the coordinate system of the parent relative to the parent docking point.

Returns:

• point - point: ideally zero Vector3f or the offset if configuration doesn't reload properly

• range - point: ideally zero Vector3f or the offset if configuration doesn't reload properly

• line - point: Vector from the beginning of the dockLine to the child docking point

• root: zero Vector3f

getMaterialProperty

(materialId: String, propertyName: String, fallback: String) : String

Retrieves additional material data defined in material properties. See Using GetMaterialPropery Function for detailed description.

Parameters:

• materialId: Id of the target material

• propertyName: name of the property on the given material

• fallback: Value to return if material or property are missing

Returns: the value stored in the material property or fallback if no material is found or if the material doesn't have the property.

Usage:

• exmaple material entry:

{
    "externalIdentifier": "fabric_blue",
    "id": "isdt:fabric_blue",
    "properties": {
        "pricegroup": "30"
    },
    ...
}

getMaterialProperty(
  'isdt:fabric_blue',
  'pricegroup',
  'NULL'
); /* returns '30' */
getMaterialProperty('isdt:fabric_blue', 'type', 'NULL'); /* returns 'NULL' */
getMaterialProperty('doesnt:exist', 'something', 'NULL'); /* returns 'NULL' */

getPosition

() : Vector3f

Get position of the child component in the coordinate system of the parent.

Returns: Vector3f leading from parent component origin to child component origin or zero Vector if component is the root component.

Usage:

position = getPosition();
parentOrigin = Vector3f{
    - xFromVector(position),
    - yFromVector(position),
    - zFromVector(position)
};

getUniqueRuntimeId

() : Integer

Returns unique runtime ID that has been assigned to this component instance in the configurator. Every root component, child component and subComponent will have an unique number. This number is not reused after for example deleting components. It is not persistent between configuration instances. Can be used to determine the timing order in which the components have been added to the configuration.

It is useful as a decision factor between two components connected via sibling points in cases that no other way to choose one component from more.

This number is not persistent between configurator instances (i.e. after configuration reload or between undo/redo actions) and in most cases, storing it as a parameter makes no sense and can lead to errors.

Example: See the Quadpost Shelf System template

Returns: Integer representing the unique runtime ID of the component in the configuration.

Usage:

/* in onUpdate */
if (isnull(uid)) {
  /* enter only in the first onUpdate call */
  uid = getUniqueRuntimeId(); /* could be for example 7 */
}
/* in a siblingPoint.assignmentScripts.onUpdate script to determine owner of the shared wall */
if (self.height > other.height) {
  self.hasSharedWall = true;
} else if (self.height < other.height) {
  self.hasSharedWall = false;
} else {
  self.hasSharedWall = self.uid > other.uid;
}

ifnull

(variable: any, fallback: any) : any

Checks if a variable is undefined or null and returns the variable or fallback. Useful for making sure a variable is defined.

Parameters:

• variable: the variable to check for null

• fallback: a value to return if varialbe is null or undefined

Returns:

• either the variable or the fallback if variable is null

Usage:

/* checks if variable 'initialized' is null and if yes, returns true in order to enter the block */
if (ifnull(initialized, true)) {
  /* make sure to initialize in order to enter only once */
  initialized = true;
}

in

(valueToCheck: any, value1: any, value2: any, ...) : boolean

Useful for checking if a list of values containes a specific value.

Parameters:

• valueToCheck: the value that is being searched for in the list

• valueN: any number of arguments that will form the list

Returns

• true if valueToCheck is equal to at least one of the other values, otherwise false

Usage:

fruit = 'banana';
isFruit = in(fruit, 'apple', 'banana', 'cherry');       /* true */
pearIsValid = in('pear', 'apple', 'banana', 'cherry');  /* false */

Most used to compare a variable to a list of constants, however you can also check a constant to a list of variables.

/* check if at least one of variables is true */
isGroceryItem = in(true, isFruit, isVegetable, isDairy);
/* which is actually equivalent to */
isGroceryItem = (isFruit + isVegetable + isDairy) > 0;

inArray

(searchedValue: float, array: [float]) : Boolean

Checks if array contains a value.

Arguments

• searchedValue: the value that is being looked for

• array: the array to check

Returns: True if array contains the value.

Usage:

inArray(1, [1, 2, 3, 1]); /* returns 1 */
inArray(10, [1, 2, 3, 1]); /* returns 0 */

indexOf

(searchedValue: float, array: [float]) : Integer

Find index of a value in an array.

Parameters:

• searchedValue: the value that is being looked for

• array: the array to search

Returns: Index of the first occurence of the value in the array or -1 if no occurence.

Usage:

indexOf(1, [1, 2, 3, 1]); /* returns 0 */
indexOf(10, [1, 2, 3, 1]); /* returns -1 */

insert

(array: [float], index: Integer, value: float | [float]) : void

Insert into array in front of the element at given index

Parameters:

• array: array into which the values are inserted

• index: index of the element before which the values will insert

• value: value to be inserted, can be a number or an array of numbers

Throws:

• [1404] index out of bounds

Usage:

arr = [10, 20];
insert(arr, 1, 15); /* arr is [10, 15, 20] */
insert(arr, 0, [0, 5]); /* arr is [0, 5, 10, 15, 20] */
insert(arr, 5, 25); /* arr stays [0, 5, 10, 15, 20], throws [1404] */
insert(arr, -1, 5); /* arr stays [0, 5, 10, 15, 20], throws [1404] */

intersection

(a: [float], b: [float]) : [float]

Intersection of arrays

Parameters:

• a, b: two arrays of numbers

Returns: Array with elements that are present in both arrays.

Usage:

intersection([3, 2, 1], [2, 3, 4, 5]); /* returns [2, 3] */
intersection([3, 2, 1], [5, 4, 3, 2]); /* returns [3, 2] */
intersection([1, 2, 3], [4, 5, 6]); /* returns [] */
intersection([1], [1, 1, 1]); /* returns [1, 1, 1] */
intersection([1, 1, 1], [1]); /* returns [1, 1, 1] */

isEnabled

(parameterKey: String) : Boolean

Returns if a parameter is enabled.

Parameters:

• parameterKey: key of the parameter

Returns: True if the parameter exists and its enabled flag is true, false otherwise.

Usage:

if (isVisible(depth)) {
  actualDepth = depth;
} else {
  /* do not take the depth parameter value but a fallback */
  actualDepth = 700;
}

isnull

(value: any) : Boolean

Checks for null values.

Parameters:

• value: identifier to be checked

Returns: True if identifier is undeclared, null or after setnull call.

Usage:

• initialize on component load, at the beginning of onUpdate

if (isnull(initialized)) {
  initialized = true;
  /* initialize values here */
}

• in a connection script of a docking range:

/* compute indeces of the docking point */
if (isnull(connection.i)) { connection.i = xFromVector(connection.position) / > offset; }
if (isnull(connection.j)) { connection.j = yFromVector(connection.position) / > offset; }

isVisible

(parameterKey: String) : Boolean

Returns if a parameter is visible.

Parameters:

• parameterKey: the parameter key to get the visible flag value from

Returns: True if the parameter exists and its enabled flag is true, false otherwise.

Usage:

if (isVisible(depth)) {
  actualDepth = depth;
} else {
  /* do not take the depth parameter value but a fallback */
  actualDepth = 700;
}

length

(array: [float])

Parameters: * array: array of floats

Returns: count of the array elements.

Usage:

a = [];
b = [0, 1, 2];
c = [0];
length(a); /* returns 0 */
length(b); /* returns 3 */
length(c); /* returns 1 */

like

(input: String, pattern: String) : Boolean

Returns true if input matches the pattern. The pattern is a String with placeholders for one any single character or any subString. This is the OPTION_LIKE operator from the IDM 3.1 standard, which itself is based to be similar on the SQL's LIKE operator.

Parameters:

• input: the String to check against the pattern

• pattern: a case sensitive String pattern, where _ is a wildcard for any single character and % is a wildcard representing any subString at least 1 character long

  • a_ - length 2, starts with a

  • a% - any String starting with a

  • _a - length 2, ends with a

  • %a - any String that ends with a

  • %a% - any String that contains a

Returns: true if String matches to the pattern, otherwise false

Usage:

like('Hello beautiful world', 'Hello') 
/* false; no wildcard, pattern means equls to 'Hello' */

like('Hello beautiful world', 'Hello%')
/* true; pattern means starts with 'Hello' */

like('Hello beautiful world', '%beatiful%')
/* true; pattern means contains 'beatiful' */

like('Hello beautiful world', '%Hello%')
/* false; pattern means contains 'Hello' which is preceded and followed by other characters */

like('Hello beautiful world', 'Hello%world')
/* true; pattern means starts with 'Hello' and ends with 'world' */

like('Hello beautiful world', 'h%';
/* false; pattern means starts with 'h' */

log

(value: float) : float

Natural logarithm

Parameters:

• value

Returns: Logarithm of the value with base of e (~2.718)

Usage:

log(100); /* returns ~4.605 */
log(M_E); /* returns 1 */
log(1); /* returns 0 */
log(0); /* returns -inf */

log10

(value: float) : float

Common logarithm

Parameters:

• value

Returns: Logarithm of the value with base of 10

Usage:

log10(100); /* returns 2 */
log10(M_E); /* returns ~0.434 */
log10(1); /* returns 0 */
log10(0); /* returns -inf */

popBack

(array: [float]) : float

Returns and removes last number from array.

Parameters:

• array

Returns: Last number of array, original array has this value removed or 0 if [1405] is thrown.

Throws:

• [1405]: popBack empty array

Usage:

arr = [10, 20];
x1 = popBack(arr); /* returns 20, arr is [10] */
x2 = popBack(arr); /* returns 10, arr is [] */
x3 = popBack(arr); /* returns 0, arr is [], throws [1405] */

pow

(value: float, exponent: float) : float

Power function

Parameters:

• value: the value to compute power

• exponent