
collection_to_list(+Collection, -List)

   Convert a "collection" into a list

Arguments
   Collection          A term to be interpreted as a collection
   List                Output list

Type
   library(lists)

Description
   Converts various "collection" data structures (and expressions
   combining them) into a list.  Fails if it does not know how to do this.
   The supported collection types are:

   List
	The list is returned unchanged. It must be terminated with [].
   Array
	The array is converted into a list, as with array_list/2.

   In addition, the following collection-valued expressions are allowed:

   Array[...]
	Subscript-reference: Extract an element or sub-array from Array.
	If a single array element is extracted, this element must itself
	be a collection (unless the result is being flattened).
   Collection1>>Collection2
	Concatenate the two collections into a single list.
   concat(Collection)
	If the collection is nested (at least 2-dimensional), the top
	level of the structure is removed and all its elements (which
	must be lists or arrays) are concatenated into a new list.
   flatten(N,Collection) - nonlogical
	If the collection is nested (multi-dimensional), the top N>=0
	nesting levels of the structure are converted into a flat list.
	In these top N levels, all subterms that look like list or array
	(including []) are interpreted as sub-collections and their
	elements added to the flattened result.
	If Collection is a single element (i.e. a non-collection term),
	the result is a single-element list containing it.
   flatten(Collection) - nonlogical
	If the collection is nested (multi-dimensional), all nesting
	structure is removed and a flat list is returned.
	If Collection is a single element (i.e. a non-collection term),
	the result is a single-element list containing it.

    NOTE: The built-in predicates eval_to_list/2 and eval_to_complete_list/2
    are logical (constraint) versions of collection_to_list/2.  These
    versions do not support flatten/1,2 because there the interpretation of
    subterms depends on their instantiation rather than just their position.


Modes and Determinism
   collection_to_list(+, -) is semidet

Fail Conditions
   Collection is not a collection or collection expression

Exceptions
     4 --- A (sub-)collection is insufficiently instantiated

Examples
      ?- List=[a,b,c,d], collection_to_list(List, Result).
   Result = [a, b, c, d]

   ?- Arr=[](a,b,c,d), collection_to_list(Arr, Result).
   Result = [a, b, c, d]

   ?- Arr=[](a,b,c,d), collection_to_list(Arr[2..3], Result).
   Result = [b, c]


   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(Mat, Result).
   Result = [[](a, b, c), [](d, e, f)]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(concat(Mat), Result).
   Result = [a, b, c, d, e, f]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(flatten(1,Mat), Result).
   Result = [a, b, c, d, e, f]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(Mat[1], Result).
   Result = [a, b, c]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(Mat[1,*], Result).
   Result = [a, b, c]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(Mat[*,2], Result).
   Result = [b, e]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(Mat[1..2,2], Result).
   Result = [b, e]

   ?- Mat=[]([](a,b,c),[](d,e,f)), collection_to_list(Mat[1..2,2..3], Result).
   Result = [[](b, c), [](e, f)]

   ?- Mat=[]([](a,b,c),[](d,e,f)),
			collection_to_list(concat(Mat[1..2,2..3]), Result).
   Result = [b, c, e, f]


   ?- NL = [a,b,[c,d]], collection_to_list(NL, Result).
   Result = [a, b, [c, d]]

   ?- NL = [a,b,[c,d]], collection_to_list(flatten(1,NL), Result).
   Result = [a, b, c, d]

   ?- NL = [a,b,[](c,d)], collection_to_list(NL, Result).
   Result = [a, b, [](c, d)]

   ?- NL = [a,b,[](c,d)], collection_to_list(flatten(1,NL), Result).
   Result = [a, b, c, d]


   ?- NA = [](a,b,[c,d]), collection_to_list(NA, Result).
   Result = [a, b, [c, d]]

   ?- NA = [](a,b,[c,d]), collection_to_list(NA[3], Result).
   Result = [c, d]


   ?- Xs=[a,b], Yz=[](c,d), collection_to_list(Xs>>Yz, Result).
   Result = [a, b, c, d]


   % Error cases where collections expected
   ?- collection_to_list(no_collection, Result).
   No (0.00s cpu)

   ?- collection_to_list(99, Result).
   No (0.00s cpu)

   ?- collection_to_list(X, Result).
   instantiation fault in collection_to_list / 2

   ?- collection_to_list(concat([[1],2,[3]]), Result).
   No (0.00s cpu)


   % Special case: force treatment of a term as single-element collection
   ?- collection_to_list(flatten(99), Result).
   Result = [99]

   ?- collection_to_list(flatten(0,99), Result).
   Result = [99]

   ?- collection_to_list(flatten(X), Result).
   Result = [X]


See Also
   eval_to_list / 2, array_list / 2, array_flat / 3, is_list / 1, is_array / 1, subscript / 3, flatten / 2, flatten / 3
