[ 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
- collection_to_list(+, -) is semidet
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