List API

Functions for creating, querying, and manipulating ordered collections.

Accessors

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

length(list)

Returns the number of elements. Also works with strings.

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

indexOf(list, needle)

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

contains(list, needle)

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

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

slice(list, start, end)

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]

concat(list1, list2)

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

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

join(list, separator)

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"

Functions that modify lists in place.

push(list, value)

Appends a value to the end.

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

pop(list)

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]

shift(list)

Removes and returns the first element. Errors if empty.

unshift(list, value)

Inserts a value at the beginning.

insert(list, index, value)

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]

remove(list, index)

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]

reverse(list)

Reverses a list in place.

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

sort(list)

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"]