[ Term Manipulation | Reference Manual | Alphabetic Index ]
# array_flat(+N, +Array, -Flat)

Flattens (reduces the number of dimensions) of a multi-dimensional array
*N*
- Integer
*Array*
- Array, i.e. structure with functor []/?
*Flat*
- Variable or array

## Description

Constructs an array Flat with the same elements, but N fewer dimensions
than Array. The most common use is to create a flat, one-dimensional
array from a multi-dimensional one. Note that multi-dimensional arrays
are in fact nested one-dimensional arrays.
N specifies how many levels are flattened: a positive value N means
that a M-dimensional array will be reduced to a (M-N)-dimensional one,
e.g. a 2-D array gets reduced to a 1-D array. When N is given as -1,
all array nesting is removed, and a 1-D array on the non-array elements
is produced. In practice, it is however recommended to always use a
positive value for N, as this avoids ambiguities with respect to the
interpretation of subterm as nested array or array element. With a
value of 0 the original array is returned unchanged.

The elements in the Flat array are in the same order as they would be
encountered in a depth-first left-to-right traversal of Array.

In the top N levels of Array, terms with functor []/M are interpreted
as arrays, in particular [] is interpreted as an empty array and thus
eliminated.

### Modes and Determinism

- array_flat(+, +, -) is det

### Exceptions

*(4) instantiation fault *
- N or Array is a variable
*(5) type error *
- N is not an integer
*(5) type error *
- Array is not an array
*(6) out of range *
- N is less than -1
*(24) number expected *
- N is not an integer, but possibly an arithmetic expression

## Examples

?- array_flat(0, []([](a,b,c),[](d,e,f)), A). % no change
A = []([](a, b, c), [](d, e, f))
?- array_flat(1, []([](a,b,c),[](d,e,f)), A). % 2-D to 1-D
A = [](a, b, c, d, e, f)
?- array_flat(2, []([](a,b,c),[](d,e,f)), A). % still 2-D to 1-D
A = [](a, b, c, d, e, f)
?- dim(M, [2,2,2]), array_flat(2, M, A). % 3-D to 1-D
M = []([]([](_368,_369), [](_365,_366)), []([](_359,_360), [](_356,_357)))
A = [](_368, _369, _365, _366, _359, _360, _356, _357)
?- dim(M, [2,2,2]), array_flat(1, M, A). % 3-D to 2-D
M = []([]([](_368,_369), [](_365,_366)), []([](_359,_360), [](_356,_357)))
A = []([](_368,_369), [](_365,_366), [](_359,_360), [](_356,_357))
% mixed-dimensional 3-D to 2-D
?- array_flat(1, [](a, [](b), []([](c)), [], d), A).
A = [](a, b, [](c) ,d).
?- array_flat(1, []([],[]), A). % empty arrays
A = []

## See Also

dim / 2, subscript / 3, array_concat / 3, is_array / 1, array_list / 2, arg / 3