@head @module std @title Class std::Array<T> @index Array @implements Sequence @implements Iterable @implements Comparable @implements Multipliable> @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