Arrays

This content is for v0.7. Switch to the latest version for up-to-date documentation.

Creating arrays

Use the #[...] literal syntax or the Array() constructor.

let empty = #[];
let nums = #[1, 2, 3, 4, 5];
let mixed = #[1, "hello", true];   // mixed types allowed

let also_nums = Array(1, 2, 3);    // same as #[1, 2, 3]

Accessing elements

Elements are zero-indexed. Use bracket notation or the .get() method.

nums[0];       // 1
nums[2];       // 3
nums.get(4);   // 5

Built-in functions

Function	Description	Example
`length(arr)`	Number of elements	`length(#[1,2,3])` → `3`
`slice(arr, start, end)`	Sub-array from start to end	`slice(#[1,2,3,4], 1, 3)` → `[2,3]`
`concat(a, b)`	Join two arrays	`concat(#[1,2], #[3,4])` → `[1,2,3,4]`
`range(n)`	Array of 0..n-1	`range(5)` → `[0,1,2,3,4]`
`range(start, end)`	Array of start..end-1	`range(2, 5)` → `[2,3,4]`

Methods

Methods are called with dot syntax on the array value.

Mutating methods

Method	Description
`.push(item)`	Append an item to the end
`.pop()`	Remove and return the last item

let chars = #["a", "b", "c"];
chars.push("d");       // ["a", "b", "c", "d"]
let last = chars.pop();  // "d", chars is now ["a", "b", "c"]

Non-mutating methods

These return new arrays; the original is unchanged.

Method	Description
`.get(index)`	Element at index
`.length()`	Number of elements
`.reverse()`	Reversed copy
`.slice(start, end)`	Sub-array
`.concat(other)`	Concatenated copy
`.contains(value)`	`true` if value is present

let nums = #[1, 2, 3, 4, 5];

nums.reverse();        // [5, 4, 3, 2, 1]
nums.slice(1, 4);      // [2, 3, 4]
nums.contains(3);      // true
nums.contains(99);     // false

let a = #[1, 2];
let b = #[3, 4];
a.concat(b);           // [1, 2, 3, 4]

Nested arrays

let matrix = #[
    #[1, 2, 3],
    #[4, 5, 6],
    #[7, 8, 9]
];
matrix[0][1];   // 2
matrix[2][2];   // 9

Higher-order methods

map

Apply a function to every element and return a new array.

let doubled = #[1, 2, 3, 4, 5].map(fn(x) { return x * 2; });
// [2, 4, 6, 8, 10]

filter

Keep only elements for which the function returns true.

let evens = #[1, 2, 3, 4, 5].filter(fn(x) { return x % 2 == 0; });
// [2, 4]

reduce

Accumulate a single value by applying a function to each element.

let sum = #[1, 2, 3, 4, 5].reduce(fn(acc, x) { return acc + x; }, 0);
// 15

Chaining

Higher-order methods can be chained:

let result = #[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    .filter(fn(x) { return x % 2 == 0; })
    .map(fn(x) { return x * x; })
    .reduce(fn(acc, x) { return acc + x; }, 0);
// 220  (sum of squares of even numbers)

Copy-on-assignment

Assignment creates an independent deep copy. Mutating one array does not affect the other.

let original = #[1, 2, 3];
let copy = original;
original.push(4);

PRINT original;   // [1, 2, 3, 4]
PRINT copy;        // [1, 2, 3]

To share state between variables, use References.

Iteration

let colors = #["red", "green", "blue"];
for color in colors {
    PRINT color;
}

Collect values during iteration:

let shout = #[];
for color in colors {
    shout.push(color + "!");
}
PRINT shout;   // ["red!", "green!", "blue!"]

Iterators

Call .iter() on an array to create a lazy iterator. Iterators process elements on demand rather than all at once, and can be chained into pipelines. Use .collect() to materialize the result back into an array.

let nums = #[1, 2, 3, 4, 5];
let it = nums.iter();
it.next();   // 1
it.next();   // 2

Lazy methods

These return a new iterator without consuming elements. Nothing happens until you call an eager method.

Method	Description
`.take(n)`	Yield the first n elements
`.skip(n)`	Skip the first n elements
`.step_by(n)`	Yield every nth element
`.enumerate()`	Yield `[index, value]` pairs
`.zip(iter)`	Pair elements from two iterators
`.chain(iter)`	Concatenate two iterators

Eager methods

These consume the iterator and return a value or array.

Method	Returns	Description
`.collect()`	Array	Gather all remaining elements into an array
`.count()`	Number	Count remaining elements
`.first()`	Value	First element (or `NUL`)
`.last()`	Value	Last element (or `NUL`)
`.next()`	Value	Next element (or `NUL` when exhausted)
`.find(fn)`	Value	First element where fn returns `true`
`.any(fn)`	Boolean	`true` if fn returns `true` for any element
`.all(fn)`	Boolean	`true` if fn returns `true` for every element
`.map(fn)`	Array	Apply fn to each element
`.filter(fn)`	Array	Keep elements where fn returns `true`
`.fold(init, fn)`	Value	Accumulate with fn(acc, elem) starting from init
`.flatten()`	Array	Flatten one level of nested arrays

take, skip, step_by

let nums = #[1, 2, 3, 4, 5];

nums.iter().take(3).collect();     // [1, 2, 3]
nums.iter().skip(2).collect();     // [3, 4, 5]
nums.iter().step_by(2).collect();  // [1, 3, 5]

enumerate

Each element becomes an [index, value] pair.

let colors = #["red", "green", "blue"];
let pairs = colors.iter().enumerate().collect();
// [[0, "red"], [1, "green"], [2, "blue"]]

zip

Pair elements from two iterators. Stops when the shorter one is exhausted.

let names = #["kick", "snare", "hat"];
let notes = #[36, 38, 42];

let pairs = names.iter().zip(notes.iter()).collect();
// [["kick", 36], ["snare", 38], ["hat", 42]]

chain

Concatenate two iterators end-to-end.

let a = #[1, 2];
let b = #[3, 4, 5];

a.iter().chain(b.iter()).collect();  // [1, 2, 3, 4, 5]

find, any, all

let nums = #[1, 2, 3, 4, 5];

nums.iter().find(fn(x) { return x > 3; });   // 4
nums.iter().any(fn(x) { return x > 4; });    // true
nums.iter().all(fn(x) { return x > 0; });    // true

flatten

Flattens one level of nested structure. Non-array elements pass through unchanged.

let nested = #[#[1, 2], #[3], #[4, 5]];
nested.iter().flatten();   // [1, 2, 3, 4, 5]

fold

Like reduce, but on iterators. Takes an initial value and an accumulator function.

let sum = #[1, 2, 3, 4, 5].iter().fold(0, fn(acc, x) { return acc + x; });
// 15

first, last

Convenience accessors for the endpoints of an iterator.

let nums = #[10, 20, 30];
nums.iter().first();   // 10
nums.iter().last();    // 30

Chaining lazy and eager methods

Lazy methods build a pipeline; an eager method at the end executes it.

let result = #[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    .iter()
    .skip(2)
    .step_by(2)
    .take(3)
    .collect();
// [3, 5, 7]