[ 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