204 lines
16 KiB
Markdown
204 lines
16 KiB
Markdown
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) |
|
|
| `extract` | 1) start position, beginning if < 0, end if > length,<br/>2) _(optional)_ number of items to extract, none if < 0 | extracts a portion of the array into a new array |
|
|
| `remove` | index | removes an element at a particular index and returns it ([`()`] 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) |
|
|
| `chop` | target length | cuts off the head of the array, leaving the tail at exactly a specified length |
|
|
| `splice` | 1) start position, beginning if < 0, end if > length,<br/>2) number of items to remove, none if < 0,<br/>3) array to insert | replaces a portion of the array with another (not necessarily of the same length as the replaced portion) |
|
|
| `filter` | [function pointer] to predicate (usually 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: _(optional)_ offset index |
|
|
| `map` | [function pointer] to conversion function (usually 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: _(optional)_ offset index |
|
|
| `reduce` | 1) [function pointer] to accumulator function (usually a [closure]),<br/>2) _(optional)_ [function pointer] to function (usually a [closure]) that provides the initial value | reduces the array into a single value via the accumulator function:<br/>1st parameter: accumulated value ([`()`] initially),<br/>2nd parameter: array item,<br/>3rd parameter: _(optional)_ offset index |
|
|
| `reduce_rev` | 1) [function pointer] to accumulator function (usually a [closure]),<br/>2) _(optional)_ [function pointer] to function (usually a [closure]) that provides the initial value | reduces the array (in reverse order) into a single value via the accumulator function:<br/>1st parameter: accumulated value ([`()`] initially),<br/>2nd parameter: array item,<br/>3rd parameter: _(optional)_ offset index |
|
|
| `some` | [function pointer] to predicate (usually a [closure]) | returns `true` if any item returns `true` when called with the predicate function:<br/>1st parameter: array item,<br/>2nd parameter: _(optional)_ offset index |
|
|
| `none` | [function pointer] to predicate (usually a [closure]) | returns `true` if no item returns `true` when called with the predicate function:<br/>1st parameter: array item,<br/>2nd parameter: _(optional)_ offset index |
|
|
| `all` | [function pointer] to predicate (usually a [closure]) | returns `true` if all items return `true` when called with the predicate function:<br/>1st parameter: array item,<br/>2nd parameter: _(optional)_ offset index |
|
|
| `sort` | [function pointer] to a comparison function (usually a [closure]) | sorts the array with a comparison function:<br/>1st parameter: first item,<br/>2nd parameter: second item,<br/>return value: `INT` < 0 if first < second, > 0 if first > second, 0 if first == second |
|
|
|
|
|
|
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]; // y == [2, 3]
|
|
|
|
let y = [2, 3,]; // y == [2, 3]
|
|
|
|
y.insert(0, 1); // y == [1, 2, 3]
|
|
|
|
y.insert(999, 4); // y == [1, 2, 3, 4]
|
|
|
|
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; // y == [1, 42, 3, 4]
|
|
|
|
(42 in y) == true;
|
|
|
|
y.remove(2) == 3; // y == [1, 42, 4]
|
|
|
|
y.len == 3;
|
|
|
|
y[2] == 4; // elements after the removed element are shifted
|
|
|
|
ts.list = y; // arrays can be assigned completely (by value copy)
|
|
|
|
ts.list[1] == 42;
|
|
|
|
[1, 2, 3][0] == 1; // indexing on array literal
|
|
|
|
fn abc() {
|
|
[42, 43, 44] // a function returning an array
|
|
}
|
|
|
|
abc()[0] == 42;
|
|
|
|
y.push(4); // y == [1, 42, 4, 4]
|
|
|
|
y += 5; // y == [1, 42, 4, 4, 5]
|
|
|
|
y.len == 5;
|
|
|
|
y.shift() == 1; // y == [42, 4, 4, 5]
|
|
|
|
y.chop(3); // y == [4, 4, 5]
|
|
|
|
y.len == 3;
|
|
|
|
y.pop() == 5; // y == [4, 4]
|
|
|
|
y.len == 2;
|
|
|
|
for item in y { // arrays can be iterated with a 'for' statement
|
|
print(item);
|
|
}
|
|
|
|
y.pad(6, "hello"); // y == [4, 4, "hello", "hello", "hello", "hello"]
|
|
|
|
y.len == 6;
|
|
|
|
y.truncate(4); // y == [4, 4, "hello", "hello"]
|
|
|
|
y.len == 4;
|
|
|
|
y.clear(); // y == []
|
|
|
|
y.len == 0;
|
|
|
|
let a = [42, 123, 99];
|
|
|
|
a.map(|v| v + 1); // returns [43, 124, 100]
|
|
|
|
a.map(|v, i| v + i); // returns [42, 124, 101]
|
|
|
|
a.filter(|v| v > 50); // returns [123, 99]
|
|
|
|
a.filter(|v, i| i == 1); // returns [123]
|
|
|
|
// Use a closure to provide the initial value
|
|
a.reduce(|sum, v| sum + v, || 0) == 264;
|
|
|
|
// Detect the initial value of '()'
|
|
a.reduce(
|
|
|sum, v| if sum.type_of() == "()" { v } else { sum + v }
|
|
) == 264;
|
|
|
|
// Detect the initial value via index
|
|
a.reduce(|sum, v, i|
|
|
if i == 0 { v } else { sum + v }
|
|
) == 264;
|
|
|
|
// Use a closure to provide the initial value
|
|
a.reduce_rev(|sum, v| sum + v, || 0) == 264;
|
|
|
|
// Detect the initial value of '()'
|
|
a.reduce_rev(
|
|
|sum, v| if sum.type_of() == "()" { v } else { sum + v }
|
|
) == 264;
|
|
|
|
// Detect the initial value via index
|
|
a.reduce_rev(|sum, v, i|
|
|
if i == 2 { v } else { sum + v }
|
|
) == 264;
|
|
|
|
a.some(|v| v > 50); // returns true
|
|
|
|
a.some(|v, i| v < i); // returns false
|
|
|
|
a.none(|v| v != 0); // returns false
|
|
|
|
a.none(|v, i| v == i); // returns true
|
|
|
|
a.all(|v| v > 50); // returns false
|
|
|
|
a.all(|v, i| v > i); // returns true
|
|
|
|
a.splice(1, 1, [1, 3, 2]); // a == [42, 1, 3, 2, 99]
|
|
|
|
a.extract(1, 3); // returns [1, 3, 2]
|
|
|
|
a.sort(|x, y| x - y); // a == [1, 2, 3, 42, 99]
|
|
```
|