Language: Lists

Lists are a collection of zero or more values.

Lists can be created using by wrapping values in [] and separating them by commas. An optional trailing comma is allowed. List elements can be differing types. Examples:

[]                  // An empty list
["foo"]             // Single element list
["foo", 1, 2, true] // Multi element list with different types
["foo", [1, 2]]     // List containing another list

A list can be sliced to create sublists. The set operators can be used to test for value inclusion in a list.

Accessing Elements

List elements can be accessed with the syntax name[index] where index is zero-indexed.

A negative index accesses the list in reverse. It is the same as reversing a list and then using a positive index. Similar to a positive index, it is bounded by the length of the list as a negative value.

Accessing beyond the length of the list results in undefined.

Examples:

a = ["foo", 1, true, [1, 2]]

a[0]    // "foo"
a[2]    // true
a[4]    // undefined
a[-2]   // true
a[-4]   // "foo"
a[-5]   // undefined
a[3][1] // 2

List Append

Values can be appended to a list using the built-in append function.

This modifies the list in-place and returns undefined. For more information on why append behaves this way, please read the full documentation for the append function.

append([1,2], 3)      // [1, 2, 3]
append([1,2], "foo")  // [1, 2, "foo"]
append([1,2], [3])    // [1, 2, [3]]
append(1, 3)          // error()

List Concatenation

Two lists can be concatenated using the + operator or the shorthand += assignment operator. For the + operator, a new list is returned. For +=, the left-hand list is modified in place.

Examples:

[1] + [2]   // [1, 2]
[1] + [[1]] // [1, [1]]
[1] + 1     // error

a = [1]
a += [2]    // a = [1, 2]
a += 3      // error

List Length

The length of a list can be retrieved using the length function.

Examples:

length([])      // 0
length(["foo"]) // 1

Removing Items From a List

You can use a combination of list concatenation and slicing to remove elements from a list.

a = [1, 2, 3, 4, 5]
a = a[:2] + a[3:] // [1, 2, 4, 5]

The shorthand shown here is effectively the same as a[0:2] + a[3:length(a)], which creates a new list out of the concatenation two sub-lists composed of the first two elements, and the rest of the list starting at index 3. This effectively removes the 3rd element from the list (index 2).

List Comparison

Lists may be compared for equality. Lists are equal if they are of equal length and their corresponding elements are comparable and equal. Lists with the same elements but in a different order are not equal.

[1, 2] is [1, 2]                       // true
[1, 2] is [2, 1]                       // false
["a"] is ["a", "b"]                    // false
["a", ["b", "c"]] is ["a", ["b", "c"]] // true

List comparison speed is O(N), meaning that the speed of the comparison is linearly proportional to the number of elements in the list. The more elements, the more iterations that are necessary to verify equality.