List API

Functions for creating, querying, and manipulating ordered collections.

Accessors

Non-destructive functions that query or derive new values from lists.

Returns the number of elements. Also works with strings.

length([1, 2, 3])    // 3
length([])            // 0

Returns the index of the first occurrence, or -1. Values compared by equality.

indexOf([10, 20, 30], 20)     // 1
indexOf([10, 20, 30], 99)     // -1

Checks whether a list contains a value. Returns true or false.

contains([1, 2, 3], 2)    // true
contains([1, 2, 3], 99)   // false

Creates a new list from a sub-range [start, end). Negative indices count from the end.

slice([10, 20, 30, 40, 50], 1, 4)   // [20, 30, 40]
slice([10, 20, 30], -2, 3)          // [20, 30]

Creates a new list by concatenating two lists. Neither original is modified.

concat([1, 2], [3, 4])    // [1, 2, 3, 4]

Converts all elements to strings and joins them with a separator.

join(["a", "b", "c"], ", ")    // "a, b, c"
join([1, 2, 3], "-")           // "1-2-3"

Mutators

Functions that modify lists in place.

Appends a value to the end.

var items = [1, 2, 3]
push(items, 4)   // items is now [1, 2, 3, 4]

Removes and returns the last element. Errors if empty.

var items = [1, 2, 3]
var last = pop(items)   // last is 3, items is [1, 2]

Removes and returns the first element. Errors if empty.

Inserts a value at the beginning.

Inserts a value at a specific position. Existing elements shift right. Negative indices count from the end.

var items = [1, 2, 4]
insert(items, 2, 3)   // items is [1, 2, 3, 4]

Removes and returns the element at a position. Negative indices count from the end.

var items = [10, 20, 30, 40]
var removed = remove(items, 1)   // removed is 20, items is [10, 30, 40]

Reverses a list in place.

var items = [1, 2, 3]
reverse(items)   // items is [3, 2, 1]

Sorts a list in place. Numbers sort before strings; strings sort before other types.

var nums = [3, 1, 4, 1, 5]
sort(nums)   // [1, 1, 3, 4, 5]

var mixed = ["b", 3, "a", 1]
sort(mixed)  // [1, 3, "a", "b"]

Bulk fills

Replace a per-element write loop with a single native pass. The fast path for clearing a grid, resetting a mask, or initializing a large list to a constant value.

Writes value into every slot of list. The list's length is unchanged. value can be any Zym value (number, bool, string, list, map, null, etc.).

var grid = [1, 2, 3, 4, 5]
fill(grid, 0)         // [0, 0, 0, 0, 0]

var flags = [true, true, true]
fill(flags, false)   // [false, false, false]

Writes value into len consecutive slots starting at index start. Negative start counts from the end (matching slice / remove). Out-of-range bounds clamp silently; negative len raises a runtime error.

var xs = [10, 20, 30, 40, 50, 60]
fillRange(xs, 2, 3, 0)    // [10, 20, 0, 0, 0, 60]

// Negative start counts from the end
var ys = [1, 2, 3, 4, 5]
fillRange(ys, -2, 2, 9)   // [1, 2, 3, 9, 9]

// Overrun clamps to the list's length
var zs = [1, 2, 3]
fillRange(zs, 1, 999, 7)  // [1, 7, 7]

See also: String API — Map API — Conversions API