rhai/doc/src/language/arrays.md

Arrays
======

{{#include ../links.md}}

Arrays are first-class citizens in Rhai. Like C, arrays are accessed with zero-based, non-negative integer indices:

> _array_ `[` _index_ `]`

Array literals are built within square brackets '`[`' ... '`]`' and separated by commas '`,`':

> `[` _value_ `,` _value_ `,` `...` `,` _value_ `]`
>
> `[` _value_ `,` _value_ `,` `...` `,` _value_ `,` `]`     `// trailing comma is OK`

All elements stored in an array are [`Dynamic`], and the array can freely grow or shrink with elements added or removed.

The Rust type of a Rhai array is `rhai::Array`.

[`type_of()`] an array returns `"array"`.

Arrays are disabled via the [`no_index`] feature.

The maximum allowed size of an array can be controlled via `Engine::set_max_array_size`
(see [maximum size of arrays].


Built-in Functions
-----------------

The following methods (mostly defined in the [`BasicArrayPackage`][packages] but excluded if using a [raw `Engine`]) operate on arrays:

| Function                  | Parameter(s)                                                                    | Description                                                                                                                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `push`                    | element to insert                                                               | inserts an element at the end                                                                                                                                                                                     |
| `append`                  | array to append                                                                 | concatenates the second array to the end of the first                                                                                                                                                             |
| `+=` operator             | 1) array<br/>2) element to insert (not another array)                           | inserts an element at the end                                                                                                                                                                                     |
| `+=` operator             | 1) array<br/>2) array to append                                                 | concatenates the second array to the end of the first                                                                                                                                                             |
| `+` operator              | 1) first array<br/>2) second array                                              | concatenates the first array with the second                                                                                                                                                                      |
| `insert`                  | 1) element to insert<br/>2) position (beginning if <= 0, end if >= length)      | inserts an element at a certain index                                                                                                                                                                             |
| `pop`                     | _none_                                                                          | removes the last element and returns it ([`()`] if empty)                                                                                                                                                         |
| `shift`                   | _none_                                                                          | removes the first element and returns it ([`()`] if empty)                                                                                                                                                        |
| `remove`                  | index                                                                           | removes an element at a particular index and returns it, or returns [`()`] if the index is not valid                                                                                                              |
| `reverse`                 | _none_                                                                          | reverses the array                                                                                                                                                                                                |
| `len` method and property | _none_                                                                          | returns the number of elements                                                                                                                                                                                    |
| `pad`                     | 1) target length<br/>2) element to pad                                          | pads the array with an element to at least a specified length                                                                                                                                                     |
| `clear`                   | _none_                                                                          | empties the array                                                                                                                                                                                                 |
| `truncate`                | target length                                                                   | cuts off the array at exactly a specified length (discarding all subsequent elements)                                                                                                                             |
| `filter`                  | 1) array<br/>2) [function pointer] to predicate (can be a [closure])            | constructs a new array with all items that returns `true` when called with the predicate function:<br/>1st parameter: array item,<br/>2nd parameter: offset index (optional)                                      |
| `map`                     | 1) array<br/>2) [function pointer] to conversion function (can be a [closure])  | constructs a new array with all items mapped to the result of applying the conversion function:<br/>1st parameter: array item,<br/>2nd parameter: offset index (optional)                                         |
| `reduce`                  | 1) array<br/>2) [function pointer] to accumulator function (can be a [closure]) | constructs a new array with all items accumulated by the accumulator function:<br/>1st parameter: accumulated value ([`()`] initially),<br/>2nd parameter: array item,<br/>3rd parameter: offset index (optional) |


Use Custom Types With Arrays
---------------------------

To use a [custom type] with arrays, a number of array functions need to be manually implemented,
in particular `push`, `insert`, `pad` and the `+=` operator.  In addition, the `==` operator must be
implemented for the [custom type] in order to support the `in` operator which uses `==` to
compare elements.

See the section on [custom types] for more details.


Examples
--------

```rust
let y = [2, 3];             // array literal with 2 elements

let y = [2, 3,];            // trailing comma is OK

y.insert(0, 1);             // insert element at the beginning
y.insert(999, 4);           // insert element at the end

y.len == 4;

y[0] == 1;
y[1] == 2;
y[2] == 3;
y[3] == 4;

(1 in y) == true;           // use 'in' to test if an item exists in the array
(42 in y) == false;         // 'in' uses the '==' operator (which users can override)
                            // to check if the target item exists in the array

y[1] = 42;                  // array elements can be reassigned

(42 in y) == true;

y.remove(2) == 3;           // remove element

y.len == 3;

y[2] == 4;                  // elements after the removed element are shifted

ts.list = y;                // arrays can be assigned completely (by value copy)
let foo = ts.list[1];
foo == 42;

let foo = [1, 2, 3][0];
foo == 1;

fn abc() {
    [42, 43, 44]            // a function returning an array
}

let foo = abc()[0];
foo == 42;

let foo = y[0];
foo == 1;

y.push(4);                  // 4 elements
y += 5;                     // 5 elements

y.len == 5;

let first = y.shift();      // remove the first element, 4 elements remaining
first == 1;

let last = y.pop();         // remove the last element, 3 elements remaining
last == 5;

y.len == 3;

for item in y {             // arrays can be iterated with a 'for' statement
    print(item);
}

y.pad(10, "hello");         // pad the array up to 10 elements

y.len == 10;

y.truncate(5);              // truncate the array to 5 elements

y.len == 5;

y.clear();                  // empty the array

y.len == 0;

let a = [42, 123, 99];

a.map(|v| v + 1);           // [43, 124, 100]

a.map(|v, i| v + i);        // [42, 124, 101]

a.filter(|v| v > 50);       // [123, 99]

a.filter(|v, i| i == 1);    // [123]

a.reduce(|sum, v| {
    // Detect the initial value of '()'
    if sum.type_of() == "()" { v } else { sum + v }
) == 264;

a.reduce(|sum, v, i| {
    if i == 0 { v } else { sum + v }
) == 264;
```