
array_flat(+N, +Array, -Flat)

   Flattens (reduces the number of dimensions) of a multi-dimensional array

Arguments
   N                   Integer
   Array               Array, i.e. structure with functor []/?
   Flat                Variable or array

Type
   Term Manipulation

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 --- N or Array is a variable
     5 --- N is not an integer
     5 --- Array is not an array
     6 --- N is less than -1
    24 --- 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
