Module array: Array Functions

This module provides utility functions to create, manipulate, search and sort arrays.

array.concat

• function concat(array1, array2, ...) → Array

Concatenates all arguments to a single array and returns it. Any keys of the arrays are copied to the resulting array. If the same key occurs more than once, the key will reference the element where it occurred last.

a=[1, 2, "three":3, 4, 5];
b=[7, "eight":8];
c=array.concat(a, b, [9]);
print c, c["eight"]
→ [1,2,3,4,5,7,8,9] 8
print keys(c)
→ [null,null,three,null,null,null,eight,null]

array.copy

• function copy(array, start=0) → Array
• function copy(array, start, length) → Array
• function copy(array, indices) → Array

Extracts a copy of array:

Only the array is copied, its elements remain the same (this is only relevant if the elements are themselves arrays).

Any keys of the copied elements are also copied to the new array.

Throws ExcIndexOutOfRange if not 0 <= start <= len(array), or if not 0 <= length <= len(array) - start, or if any 0 <= indices[i] < len(array).

a=[1, 2, "three":3, 4, 5];
print array.copy(a)
→ [1,2,3,4,5]
print array.copy(a, 3)
→ [4,5]
b=array.copy(a, 1, 3);
print b, b["three"]
→ [2,3,4] 3
print array.copy(a, [3, 2])
→ [4, 3]

array.create

• function create(len, initval) → Array
• function create(len1, len2, ..., lenn, initval) → Array

Creates a one-dimensional array of length len, or a multi-dimensional array of arrays, with dimensions len1 x len2 x ... x lenn, with all array elements set to initval.

a=array.create(3,3,0); // create a 3x3 matrix of zeros
print a
→ [[0,0,0],[0,0,0],[0,0,0]]
b=array.create(10, "x"); // create an array of ten "x"
print b
→ [x,x,x,x,x,x,x,x,x,x]

array.fill

• function fill(array, val, start=0) → null
• function fill(array, val, start, length) → null

Sets the elements of array array to val, from element start to the end of the array, or length elements.

Throws ExcIndexOutOfRange if not 0 <= start <= len(array), or if not 0 <= length <= len(array) - start.

a=[1,2,3,4,5];
array.fill(a, 0);
print a
→ [0,0,0,0,0]
array.fill(a, false, 1, 2);
print a
→ [0,false,false,0,0]

array.index

• function index(array, val, start=0) → Number

Searches the array array for the first element at or after start equal to val, and returns the index of the element. If there is no such element, returns -1. Elements are compared using the builtin function .equal.

Throws ExcIndexOutOfRange if not 0 <= start <= len(array).

a=["To", "be", "or", "not", "to", "be"];
print array.index(a, "be")
→ 1
print array.index(a, "Be")
→ -1
print array.index(a, "be", 2)
→ 5
print array.index(a, "be", 6)
→ -1

See also: array.rindex

array.insert

• function insert(array, pos, element, ...) → null

Inserts one or more elements into array before position pos. The elements at or after pos are moved up. The length of array is increased by the number of elements inserted.

Throws ExcIndexOutOfRange if not 0 <= pos <= len(array).

arr=[29, 18, -4];
array.insert(arr, 2, 17, "x");
print arr
→ [29,18,17,x,-4]

See also: .append

array.isort

• function isort(array, desc=false, mode=raw, ind=[0,1,...,len(array)-1]) → Array

Sorts the indices ind such that the elements array[ind[i]] are sorted in ascending order, or in descending order if desc=true, and returns the sorted indices.

String comparisons are performed according to mode[2] (one of array.raw, array.fold, array.collate).

Throws ExcNotComparable if the elements of interest in array are not all numbers or not all strings.

Throws ExcIndexOutOfRange if any element of ind does not properly index into array.

See also: array.sort, array.copy

a=[412,-302,18,2077,22,149,18];
ind=array.isort(a);
print ind
→ [1,2,6,4,5,0,3]
print array.copy(a, ind)
→ [-302,18,18,22,149,412,2077]
print array.isort(a, true)
→ [3,0,5,4,2,6,1]
a=["To", "be", "or", "not", "to", "be"];
print array.isort(a)
→ [0,1,5,3,2,4]
print array.isort(a, false, array.fold)
→ [1,5,3,2,0,4]
print array.isort(a, false, array.fold, [1,2,3])
→ [1,3,2]

array.leindex

• function leindex(arr, val, mode=raw) → Number

Searches the sorted array arr for the first index of the largest element less than or equal to val. Comparisons use the specified mode (one of array.raw, array.fold, array.collate).

Returns -1 if all elements of arr are larger than val.

Since the array is sorted, searching can be performed much more efficiently than with an unsorted array. The difference is however only noticable for relatively large arrays (around 100 elements or more).

a=[412,-302,18,2077,22,149,18,21];
array.sort(a);
print a
→ [-302,18,18,21,22,149,412,2077]
print array.leindex(a, 22)
→ 4
print array.leindex(a, 3000)
→ 8
print array.leindex(a, -3000)
→ -1
print array.leindex(a, 18)
→ 1

array.new

• function new(size=0, foldedkeys=false) → Array

Creates a new array of length 0, with pre-allocated capacity for up to size elements.

For large arrays, pre-allocating the correct size is considerably more efficient. It avoids reallocating and copying the array contents, and it ensures the array being of minimal size. On the other hand, besides effects on memory needs and runtime, pre-allocating an array will never change the result of any computation in m.

If foldedkeys=true, the string keys of the array are compared folded, i.e. are not case sensitive. This is the only way of creating an associative array with keys that are not case sensitive.

a=array.new(1000);
for i=1 to 1000 do
  append(a, i) // will never allocate memory
end;
a=array.new(); // same as a=[]
print a
→ []
a=array.new(5, true); // keys of a ignore case
a["one"] = 1;
a["ONE"] = 2;
print a, keys(a)
→ [2] [one]

array.remove

• function remove(array, start, length=1) → null
• function remove(array, key) → null

Removes one or several elements from array. The elements after the removed one(s) are shifted accordingly, and the length of array is reduced by the number of removed elements.

The first form removes a region of length length, starting at start. It throws ExcIndexOutOfRange if not 0 <= start <= len(array), or if not 0 <= length <= len(array) - start.

The second form removes the single element with string key key. It throws ExcNoSuchKey if this key does not exist.

a=["one":1, "two":2, 3, "four":4, 5];
array.remove(a, 3);
print a, keys(a)
→ [1,2,3,5] [one,two,null,null]
array.remove(a, "one");
print a, keys(a)
→ [2,3,5] [two,null,null]
array.remove(a, 0, 3);
print a, keys(a)
→ [] []

array.rindex

• function rindex(array, val, start=len(array)-1) → Number

Searches the array array for the first element at or before start equal to val, and returns the index of the element. If there is no such element, returns -1. Elements are compared using the builtin function .equal.

Throws ExcIndexOutOfRange if not -1 <= start < len(array).

a=["To", "be", "or", "not", "to", "be"];
print array.rindex(a, "be")
→ 5
print array.rindex(a, "Be")
→ -1
print array.rindex(a, "be", 4)
→ 1
print array.rindex(a, "be", 0)
→ -1

See also: array.index

array.sort

• function sort(array, desc=false, mode=raw) → null

Sorts the array array in ascending order, or in descending order if desc=true. String comparisons are performed according to mode [3] (one of array.raw, array.fold, array.collate, see below).

Throws ExcNotComparable if the elements are not all numbers or not all strings.

See also: array.isort

a=[412,-302,18,2077,22,149,18];
array.sort(a);
print a
→ [-302,18,18,22,149,412,2077]
array.sort(a, true);
print a
→ [2077,412,149,22,18,18,-302]
a=["To", "be", "or", "not", "to", "be"];
array.sort(a);
print a
→ [To,be,be,not,or,to]
array.sort(a, false, array.fold);
print a
→ [be,be,not,or,To,to]
a=["one":1, "two":2, 3, "four":4, 5];
array.sort(a, true);
print a, keys(a)
→ [5,4,3,2,1] [null,four,null,two,one]

array Constants

• const collate = 2 This mode correctly compares accents and umlauts, depending on the current locale.

• const fold = 1 This mode ignores case when comparing.

• const raw = 0 This mode directly compares 16-bit character codes.

© 2004-2010 airbit AG, CH-8008 Zürich
Document AB-M-LIB-871