[ library(lists) | Reference Manual | Alphabetic Index ]

collection_to_list(+Collection, -List)

Convert a "collection" into a list
Collection
A term to be interpreted as a collection
List
Output list

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

Fail Conditions

Collection is not a collection or collection expression

Exceptions

(4) instantiation fault
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