[ Term Manipulation | Reference Manual | Alphabetic Index ]
# dim(?Array, ?Dimensions)

Creates a multi-dimensional array or or computes the dimensions of an existing one
*Array*
- Variable or array.
*Dimensions*
- Variable or list of integers.

## Description

Creates an array of arbitrary dimensions, or determines the dimensions
of an existing one. Multi-dimensional arrays are represented in the
form of nested structures.
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

arg / 3, arity / 2, subscript / 3, array_flat / 3, functor / 3