dim(?Array, ?Dimensions)

Array

Variable or array.

Dimensions

Variable or list of integers.

Description

When creating an array of dimensions [D1,..,Dn], a nested structure is created with the top-level term having the functor []/D1, its arguments being structures with functor []/D2, and so on. The functor [] is chosen to remind of arrays.

Empty arrays: the atom [] represents the empty array of any dimension. This means that dimensions like [0], [3,0] and [3,0,4] all lead to the creation of the empty array [].

When determining the dimensions of an existing array, this predicate only considers the sub-arrays on index position 1. It is therefore not reliable for ragged arrays.

To get the size of one-dimensional arrays, it is more efficient to use arity/2.

Modes and Determinism

• dim(+, -) is det
• dim(-, ++) is det

Exceptions

(4) instantiation fault

Both Array and Dimensions are not sufficiently instantiated.

(5) type error

Array is not an array (term with functor []/N).

(5) type error

Dimensions is not a list of integers.

(6) out of range

An integer in Dimensions is negative.

(6) out of range

Dimensions is the empty list.

Examples

?- dim(M, [3,4]).
M = []([](_131, _132, _133, _134),
       [](_126, _127, _128, _129),
       [](_121, _122, _123, _124))
yes.

?- dim(M, [3,4]), dim(M, L).
M = []([](_131, _132, _133, _134),
       [](_126, _127, _128, _129),
       [](_121, _122, _123, _124))
L = [3, 4]
yes.

?- dim(M, [0]).
M = []
yes.

?- dim(A, []).
out of range in dim(A, [])

See Also