# Array-functions

All array-functions are statically bound to "array" -namespace. Namespace may be omitted, unless otherwise instructed in the notes. If output-type is other than Array then it is explicitly written out.

- count() <Number>
- first()
- first($count <Number>)
- last()
- last($count <Number>)
- get($index <Number>) <JSON>
- sum() <Number>
- min() <Number>, min($comparator) <JSON>
- max() <Number>, max($comparator) <JSON>
- avg() <Number>
- distinct()
- reduce($expr) <JSON>
- flatten()
- forAll($test) <Boolean>
- forAtLeast($count, $test) <Boolean>
- forAtMost($count, $test) <Boolean>
- forEach($expr)
- forEachPair($array, $expr)
- groupBy() <Object>
- groupBy($by) <Object>
- search($test)
- sort()
- sort($comparator)
- random($options <Object>)
- remove($index <Number>)
- reverse()
- rotate($distance <Number>)
- shuffle()
- toPath() <Path>
- update($value, $target <Number Or Array>)
- swap($a <Number>, $b <Number>)
- insertBefore($value, $position <Number>)

## first($count <Number>)

First (with $count-argument) returns the first $count number of items from an input-Array.

**Example**

## last($count <Number>)

Last (with $count-argument) returns the last $count number of items from an input-Array.

**Example**

## get($index <Number>) <JSON>

Get returns the item from the given index from an input-Array.

- Index 0 means none of the items in the array.
- Index 1 means the first item in the array.
- Index 2 means the second item in the array, etc.
- Index -1 means the last item in the array.
- Index -2 means the second last item in the array, etc.
- Index -n, where n is the size of the array + 1, means the whole array.

**Example**

## sum() <Number>

Sum sums all the Array-items and results into a Number-value. Sum assumes that all values in an Array are Number-type.

**Example**

## min() <Number>

Min returns the minimum value from an Array. Min without arguments assumes that array-items are either number or string, but not mixed.

**Example**

## min($comparator) <JSON>

Min returns the minimum value from an Array based on the $comparator expression. Comparator takes implicit params $a and $b, which Operon injects for it from the array's adjacent items. Comparator must return -1 when $a is less than $b, 0 when $a and $b are equal, and 1 when $b is greater than $a.

**Example**

## max() <Number>

Max returns that maximum value from an Array. Max without arguments assumes that array-items are either number or string, but not mixed.

**Example**

## max($comparator) <JSON>

Max returns the maximum value from an Array based on the $comparator expression. Comparator takes implicit params $a and $b, which Operon injects for it from the array's adjacent items. Comparator must return -1 when $a is less than $b, 0 when $a and $b are equal, and 1 when $b is greater than $a.

**Example**

## avg() <Number>

Avg calculates the average value from an Array. Avg assumes that all values in an Array are Number-type.

**Example**

## distinct()

Distinct returns the distinct values from an input-Array, which means that the duplicate-values are removed.

**Example**

## reduce($expr, $options) <JSON>

Reduce uses $expr to combine the values so that in the end all values are combined into one value. The $expr can be a normal expression, Lambda- or Function-reference. Note that all expressions must be parametrized with values $a and $b, which Operon will inject with the correct Array-values.

$options -object is optional and has the following fields:

- initialValue: any JSON-value
- direction: either "right" or "left"

**Example**

**Example**

**Example**

**Example**

## flatten()

Flatten takes the items from the sub-arrays and puts them into the top-level of the input-array.

**Example**

## forAll($test) <Boolean>

ForAll returns true if all items satisfy the predicate-expression $test, otherwise false is returned. The $test can be a normal predicate-expression, a Lambda- or Function-reference.

If Lambda -reference is used, then the parameter $a is expected for Lambda, and it will receive the single value from the array to be evaluated.

If Function -reference is used, then the parameter-name may be freely chose, and it will receive the single value from the array to be evaluated.

The @ will be the whole input-array for both cases.

**Example**

**Example**

**Example**

## forAtLeast($count <Number>, $test) <Boolean>

ForAtLeast returns true if at least $count items satisfy the predicate-expression $test, otherwise false is returned. The $test can be a normal predicate-expression, a Lambda- or Function-reference.

If Lambda -reference is used, then the parameter $a is expected for Lambda, and it will receive the single value from the array to be evaluated.

If Function -reference is used, then the parameter-name may be freely chose, and it will receive the single value from the array to be evaluated.

The @ will be the whole input-array for both cases.

**Example**

**Example**

## forAtMost($count <Number>, $test) <Boolean>

ForAtMost returns true if at most $count items satisfy the predicate-expression $test, otherwise false is returned. The $test can be a normal predicate-expression, a Lambda- or Function-reference.

If Lambda -reference is used, then the parameter $a is expected for Lambda, and it will receive the single value from the array to be evaluated.

If Function -reference is used, then the parameter-name may be freely chose, and it will receive the single value from the array to be evaluated.

The @ will be the whole input-array for both cases.

**Example**

**Example**

## forEach($expr)

ForEach applies $expr for each item in an input-array. Empty input-array will cause an error. Expression $expr can be a normal expression, Lambda-, or a Function-reference.

The @ will be the whole input-array for both Lambda- and Function reference.

When normal expr is used, then the current-value will be the single value from the array that is being evaluated.

**Example**

**Example**

**Example**

## forEachPair($array, $expr)

ForEachPair applies the expression $expr for both the input array and the param $array, combining the result in an array. The expression must be parametrized with values $a and $b. Param $a refers to input-array and param $b refers to an array in param $array.

**Example**

**Example**

## groupBy() <Object>

GroupBy without any arguments creates an object, with keys named as "1", "2", "3", ... , "n", where each key is associated with the value from an input-array. Therefore this function basically transforms an array into an object.

NOTE: when accessing an object, which has a key like "1", we must use object:value($index) -function instead of trying to access it with dot-notation.**Example**

## groupBy($by) <Object>

GroupBy with $by -argument collects the items from an input-array and puts those items in the same array which match the $by-expression. The $by-expression must return String or Array. String will be used as the group-name. Array must contain Strings, which will be used 1-to-1 for each item. The $by-expression may be a normal expression, Function- or Lambda-reference.

**Example**

**Example**

**Example**

**Example**

## search($test)

Search finds all indexes that satisfy the predicate-expression $test. The result is an array.

**Example**

## sort()

Sort sorts the input-array based on natural order, which is defined for numbers and strings.

**Example**

## sort($comparator)

Sort with $comparator-argument sorts the input-array based on the $comparator-expression. Comparator takes implicit params $a and $b, which Operon injects for it from the array's adjacent items. Comparator must return -1 when $a is less than $b, 0 when $a and $b are equal, and 1 when $b is greater than $a.

**Example**

## random($options <Object>)

Random takes the $count amount of values from the input-array. If $count is not given, then only one value is returned.

#### Options

- $count tells how many values are taken.
- $allowSame (Boolean, default: true) controls if the same index may be picked multiple times.
- $seed (Number, optional) controls the seed for the pseudo random-number generator.

**Example**

## remove($index <Number>)

Remove removes the item from the input-array, from the position that is given with $index-argument.

**Example**

## rotate($distance <Number>)

Rotate moves the input-array items to a given number of steps either to right (when $distance is positive) or left (when $distance is negative).

**Example**

**Example**

**Example**

## update($value, $target <Number Or Array>)

Update changes the value from the $target -position into the value given with $value-argument. If no $target is given, then all items are updated.

**Example**

**Example**