>
@supertypes
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:
@example
[] -- Empty array
[1] -- Single-item array
[1, 2, 3] -- Array with 3 items
@end
An array of an arbitrary length can be
constructed using the * operator. Example:
@example
var n = 4
[0] * n -- [0, 0, 0, 0] (array with 4 zeroes)
@end
You can also create an array from any iterable object using the
Array constructor:
@class Array([iterable as Iterable])
@desc 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:
@example
Array(0 to 3) -- [0, 1, 2]
@end
@end
Array methods
@fun length() as Int
@desc Return the length of the array.
@end
@fun append(object as T)
@desc Add an item at the end of the array. The length of the array is increased
by one.
@end
@fun extend(sequence as Sequence)
@desc Add the items in the sequence to the end of the array. Example:
@example
var a = [1, 2]
a.extend([3, 4]) -- a becomes [1, 2, 3, 4]
@end
@end
@fun insertAt(index as Int, object as T)
@desc 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.
@end
@fun remove(object as T)
@desc Remove all instances of the object from array. The length of array is
decreased by one for each removed instance.
@end
@fun removeAt(index as Int) as T
@desc Remove an item at the specified index, and return the item.
The length of the array is decreased by one.
@end
@fun index(item as Object) as Int
@desc Return the smallest (non-negative) index of the array that contains the
item, or raise @ref{ValueError} if the array does not contain the item.
@end
@fun count(item as Object)
@desc Return the number of times an item is present in the array.
@end
@fun iterator() as Iterator
@desc Return an iterator object that can be used to sequentially iterate over
the array items, starting from the first item.
@end
@fun copy() as Array
@desc 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.
@end
@end
@fun find(item as Object) as Int
@desc @deprecated
Return the smallest (non-negative) index of the array that contains the
item, or -1 if the array does not contain the item.
@end
Array operations
Array objects support the following operations:
@op array[n] @optype{Array[Int] -> T}
@desc Access an array item at integer index n.
Raise @ref{IndexError} if the index is out of bounds.
@example
var a = ["a", "b", "c"]
a[0] -- "a"
a[1] -- "b"
a[-1] -- "c"
@end
@end
@op array[n] = x @optype{Array[Int] = T}
@desc Modify an array item at integer index n. Raise @ref{IndexError}
if the index is out of bounds.
@example
var a = ["a", "b", "c"]
a[1] = "1" -- a == ["a", "1", "c"]
@end
@end
@op array[x : y] @optype{Array[Pair] -> Array}
@desc 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.
@example
var a = ["a", "b", "c"]
a[1:5] -- ["b", "c"]
a[:2] -- ["a", "b"]
a[-2:] -- ["b", "c"]
@end
@end
@op array * n @optype{Array * Int -> Array}
@op n * array @optype{Int * Array -> Array}
@desc 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:
@example
[0] * 5 -- [0, 0, 0, 0, 0]
[1, "x"] * 2 -- [1, "x", 1, "x"]
[x] * 0 -- []
@end
@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.
@end
@end
@op for x in array @optype{for T in Array}
@desc Array items can be enumerated with a for loop, starting from the first
item.
@end
@op array == x @optype{Array == Object -> Boolean}
@op array < x, array > x
@desc 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.
@end
@op x in array @optype{Object in Array}
@desc 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.
@end
@op x, y, z = array
@desc 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.
@example
var a = [1, 3, 5]
var x, y, z = a -- x gets 1, y gets 3, z gets 5
@end
@end
@op array + x @optype{Array + Array -> Array}
@desc Concatenate two arrays. Return a new array that contains
the concatenation of the operand arrays.
@end
@op Str(array)
@desc Return a string representation of the array contents.
@end
@op Hash(array)
@desc Return the hash value of an array.
@end