apply() Function

Calls a rule or function for each item in a list, and provides any contexts specified.

Related functions:

• merge(): Combine multiple lists into argument sets for use with apply().
• a!localVariables(): Cannot be used inside apply(); use a!forEach() instead.
• load(): Cannot be used inside apply(); use a!forEach() instead.
• a!applyComponents(): Use instead of apply() when working with interface components that store local data.

Parameters

apply( function, list, context )

Returns

Any Type Array

Using the function

The following sections cover important details about the apply() function.

Using the function parameter

In the function parameter of apply(), enter fn!functionName to reference an expression function, or rule!ruleName to reference a rule.

Using rules or functions with multiple arguments

To use rules or functions that take more than one argument, use the merge() function. For example, given a rule g(x, y), apply(rule!g, merge({a, b, c}, {d, e, f})) returns {g(a, d), g(b, e), g(c, f)}.

Understanding results

The apply() function returns a null list without executing the function when the list parameter is null.

The result of each operation is appended to each other in the same order as their corresponding item in the input list. If the result of each operation is an array, apply() returns a two-dimensional array which can then be used for further computation. When the two-dimensional array is saved into a process variable, a node input, or a custom data type, the array is flattened to a one-dimensional array. Local variables can store the two-dimensional array without flattening it.

Flattening data

If you save the nested arrays into a process variable for multiple values, the nested function is flattened. Casting to a flattened array only happens when saving into a process variable, node input, custom data type, or custom data type field.

To avoid having the nested function flatten, you can use the output of the apply() function as the input for a merge() function.

Unsupported functions

The apply() function cannot be used with rules or functions that store local data. This means any local variable that can be saved into, such as variables created using load() or a!localVariables() without using the "refreshAlways" configuration, cannot be created. Additionally, a!forEach() and some components cannot be used.

In these cases, use a!forEach() or a!applyComponents() instead of apply().

Examples

The following examples demonstrate the apply() function.

To experiment with examples, copy and paste the expression into an expression rule and click TEST RULE to see the output.

Adding a value to each item in a list

1
apply(fn!sum, {-1, 2, 3}, 2)

Returns {1, 4, 5}.

Feature compatibility

Feedback