std::Array class

The Array class is a resizable sequence of items. The items can be arbitrary values, and a single Array object can contain objects of several different types. The items are indexed using increasing integers, starting from 0 which refers to the first item. Each item can also be accessed using a negative index: -1 refers to the last item, -2 to the second to last item, etc.

class Array()

Construct an empty Array object. An array of length n can be constructed using the multiplication operator: [init] * n (see below).

Array methods

length()

Return the length of the array.

append(object)

Add an item at the end of the array. The length of the array is increased by one.

insertAt(index, object)

Insert an item at the specified position. The length of the array is increased by one. The index argument is the index of the inserted object: for example, array.insertAt(0, x) inserts x as the first item of a array, shifting any other elements in the array to a higher index.

removeAt(index)

Remove an item at the specified index. The length of the array is decreased by one.

find(item)

Return the smallest (non-negative) index of the array that contains the item, or -1 if the array does not contain the item.

index(item)

Return the smallest (non-negative) index of the array that contains the item, or raise ValueError if the array does not contain the item.

count(item)

Return the number of times an item is present in the array.

iterator()

Return an iterator object that can be used to sequentially iterate over the array items, starting from the first item.

copy()

Return a new array object with the same length and the same items as the original array.

Note: Only item references are copied to the new array — the items itself are not duplicated.

Array operations

Array objects support the following operations:

array[n]

Access and modify array items, including subsequences, with the indexing operator. The index n must an integer or a pair. If the index is an integer, an IndexError exception is raised if the index is not within bounds.

Indexing with a pair x : y constructs a new array object that contains the items a[x], a[x + 1], ..., a[y - 1] in the original array a (negative indices are first normalized to equivalent positive values). It cannot be used for modifying array items. Subarray indexing succeeds even if the range bounds are not within the valid range of array indices. In this case, the bounds are clipped to lie within the valid range of values. If the left value of the pair is omitted (or is nil), it is assumed to be 0. If the right value is omitted or nil, the result is a subarray extending to the end of the array.

var a = ["a", "b", "c"]
a[1]        -- "b"
a[-1]       -- "c"
a[1:3]      -- ["b", "c"]
a[:2]       -- ["a", "b"]
a[1:]       -- ["b", "c"]

array * n

Construct an Array object which contains the items in the array operand repeated n times. The operand n must must be a non-negative integer. Example:

[0] * 5             -- [0, 0, 0, 0, 0]
[1, "x"] * 2        -- [1, "x", 1, "x"]
[x] * 0             -- []

Note: The items in the new array will point to the same objects as in the original array. Thus this operation is not useful for constructing multidimensional arrays.

for x in array

Array items can be enumerated with a for loop, starting from the first item.

array == x, array < x

Arrays can be compared for equality and for lexicographic order. All the basic comparison operators are supported: ==, !=, <, <=, > and >=.

x in array

Test whether an array contains a specific object. Return a boolean value. The test is not recursive, i.e., arrays within arrays are not searched.

x, y, z = array

Array objects can be expanded in a multi-assignment or a variable definition. The number of items in the lvalue must equal the length of the array.

var a = [1, 3, 5]
var x, y, z = a    -- x gets 1, y gets 3, z gets 5

Str(array)

Return a string representation of the array contents.

array + x

Arrays can be concatenated together. A new array is created that contains the concatenation of the operand arrays.

Hash(array)

Return the hash value of an array.