Class std::Array<T>

Implements Sequence<T>, Iterable<T>, Comparable, Multipliable<Int, Array<T>>

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 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.

Creating arrays

Use an array expression [ ... ] to construct arrays of a specific length:

[]         -- Empty array
[1]        -- Single-item array
[1, 2, 3]  -- Array with 3 items

An array of an arbitrary length can be constructed using the * operator. Example:

var n = 4
[0] * n    -- [0, 0, 0, 0] (array with 4 zeroes)

You can also create an array from any iterable object using the Array constructor:

class Array([iterable as Iterable<T>])

Construct an Array object. If iterable is given, iterate over it and append all the items to the created array. Otherwise, the created array is empty. Example:

Array(0 to 3)      -- [0, 1, 2]

Array methods

length() as Int

Return the length of the array.

append(object as T)

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

extend(sequence as Sequence<T>)

Add the items in the sequence to the end of the array. Example:

var a = [1, 2]
a.extend([3, 4])   -- a becomes [1, 2, 3, 4]

insertAt(index as Int, object as T)

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 the array, shifting any other elements in the array to a higher index.

remove(object as T)

Remove all instances of the object from array. The length of array is decreased by one for each removed instance.

removeAt(index as Int) as T

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

index(item as Object) as Int

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 as Object)

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

iterator() as Iterator<T>

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

copy() as Array<T>

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.

find(item as Object) as Int

Deprecated (this feature will be removed in a future Alore version). Return the smallest (non-negative) index of the array that contains the item, or -1 if the array does not contain the item.

Array operations

Array objects support the following operations:

array[n] (Array<T>[Int] ⇒ T)

Access an array item at integer index n. Raise IndexError if the index is out of bounds.

var a = ["a", "b", "c"]
a[0]        -- "a"
a[1]        -- "b"
a[-1]       -- "c"

array[n] = x (Array<T>[Int] = T)

Modify an array item at integer index n. Raise IndexError if the index is out of bounds.

var a = ["a", "b", "c"]
a[1] =  "1" -- a == ["a", "1", "c"]

array[x : y] (Array<T>[Pair<Int, Int>] ⇒ Array<T>)

Construct a new array object (slice) that contains the items a[x], a[x + 1], ..., a[y - 1] in the original array (negative indices are first normalized to normal indexing). Slicing cannot modify array items. Slicing succeeds even if the range bounds are not within the valid range of array indices. In this case, clip the bounds to lie within the valid range of values. If the left value of the pair is omitted (or is nil), assume it to be 0. If the right value is omitted or nil, the result is a slice extending to the end of the array.

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

array * n (Array<T> * Int ⇒ Array<T>)

n * array (Int * Array<T> ⇒ Array<T>)

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 alone is not useful for constructing multidimensional arrays.

for x in array (for T in Array<T>)

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

array == x (Array<T> == Object ⇒ Boolean)

array < x, array > x

Arrays can be compared for equality and for lexicographic order. All the basic comparison operators are supported: ==, !=, <, <=, > and >=. Arrays can be compared with tuples, and an array and a tuple with the same items are equivalent.

x in array (Object in Array<T>)

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

array + x (Array<T> + Array<T> ⇒ Array<T>)

Concatenate two arrays. Return a new array that contains the concatenation of the operand arrays.

Str(array)

Return a string representation of the array contents.

Hash(array)

Return the hash value of an array.