Arrays (not in ISO)

An array is a collection of elements. As array elements can be arrays, arrays can be multi-dimensional. Arrays are created by the built-in predicate new_array(X,Ranges) where X must be an uninstantiated variable and Ranges must be a list of positive integers. Let Ranges be [N1,...,Nn]. Then, N1 is the size of the first dimension, N2 is the size of the second dimension, and so on. For example, the call new_array(X,[10,20]) binds X to a two dimensional array where the first dimension has 10 elements and the second dimension has 20 elements. The 200 array elements are free variables when the array is created.

The operator @= is provided for initializing and accessing arrays. The call A^[I] @= Elm unifies the Ith element of A with Elm. The index I must be an expression whose value is from 1 to the size of the array. A type exception will be raised if A is not an array. This notation extends to multi-dimensional arrays. In general, the call A^[I1,...,In] @= Elm is equivalent to:

       A^[I1] @= T, T^[I2,...,In] @= Elm

The operator @= can also be used to initialize arrays. For example,

       new_array(X,[3]), X @= [1,2,3]

creates a one-dimensional array with three integers 1, 2, and 3, and the following

       new_array(X,[2,2]), X @= [[1,2],[3,4]]

creates a two-dimensional array with four integers. Notice that lists or lists of lists are not treated as arrays in other contexts.

• new_array(X,Ranges): X is an array whose dimension sizes are specified by Ranges.  

• X^length @= Length: The length of the array X is Length. If X is a multi-dimensional array, then Length is the size of the first dimension.  

• X^dimension @= Dim: Dim is the dimension of X.  

• X^rows @= Rows: Rows is a list of rows in the array X. The dimension of X must be no less than 2.  

• X^columns @= Cols: Cols is a list of columns in the array X. The dimension of X must be no less than 2.  

• X^diagonal1 @= Diag: Diag is a list of elements in the left-up-diagonal (elements Xn1,...,X1n) of array X, where the dimension of X must be 2 and the number of rows and the number of columns must be equal.  

• X^diagonal2 @= Diag: Diag is a list of elements in the left-down-diagonal (elements X11,...,Xnn) of array X, where the dimension of X must be 2 and the number of rows and the number of columns must be equal.  

• is_array(A): Succeeds if A is an array.

• X^Indexes @= Elm: The element at Indexes of the array X is Elm. Indexes must be a list of integers [I1,I2,...,In] where Ii must be an integer in the range from 1 to the size of the corresponding dimension. Notice that indexes start from 1, which is different from in many other languages.

• X^Indexes @:= Elm: Destructively replace the element at Indexes of the array X by Elm. The update is undone upon backtracking.  

• array_to_list(X,List): The term List is a list of all elements in array X. Suppose X is an n dimensional array and the sizes of the dimensions are N1, N2, ..., and Nn. Then List contains the elements from [1,...,1], [1,...,2], to [N1,N2,...,Nn].