[ Term Manipulation | Reference Manual | Alphabetic Index ]

# eval_to_list(?Collection, ?Result)

Equate a "collection" expression with a list

Collection
  A term to be interpreted as a collection
Result
  The collection as list

## Description

This is a constraint establishing equality between a collection-valued expression and a list containing the same elements as the collection. Evaluation delays if arguments are insufficiently instantiated.

A "collection" can be either of the following data terms:

List
  The list is returned unchanged.
Array
  The array is converted into a list, as with array_list/2.

In addition, the following "collection 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 (array or list).
CollectionExpr1>>CollectionExpr2
  The result is the concatenation of the two collections.
concat(CollectionExpr)
  If the collection is nested (at least 2-dimensional), the top level of the structure is removed and the result is the concatenation of all its elements (which must be collections themselves).
eval(X)
  If X is a list, array or collection expression, then eval(X) is equivalent to X alone. If X is uninstantiated, then eval(X) indicates that X might be instantiated to any collection expression term. Without the eval/1 wrapper, a free X is interpreted as an uninstantiated list.

### Modes and Determinism

- eval_to_list(?, ?) is semidet

### Fail Conditions

Collection is not a collection expression, or Result does not unify with the evaluation result

## Examples

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

       % Cases with insufficient instantiation:

       ?- eval_to_list(Xs, R).
       R = Xs                % assumed to be a list (but no check)
       Yes

       ?- eval_to_list([1|Xs], R).
       R = [1|Xs]
       Yes

       ?- eval_to_list(Xs>>[3], R).
       R = R
       <delays until Xs instantiated>

       ?- eval_to_list([1]>>Ys, R).
       R = [1|Ys]                % assumed to be a list (but no check)
       Yes

       ?- eval_to_list([1]>>Ys, R).
       R = [1|Ys]                % assumed to be a list (but no check)
       Yes

       ?- Mat=[]([](a,b,c),[](d,e,f)), eval_to_list(Mat[I], R).
       R = R
       <delays until I instantiated>

       % Delayed instantiation of expression
       ?- eval_to_list(eval(X), [1,2,3]).
       X = X
       <delays until X instantiated>

       ?- eval_to_list(eval(X), Ys), X=[1]>>[2,3].
       Ys = [1, 2, 3]

       ?- eval_to_list(eval(X), [1,2,3]), X=[](1,2,3).
       Yes

       % Reverse direction
       ?- eval_to_list(Xs, [1,2,3]).
       Xs = [1,2,3]
       Yes

## See Also

eval_to_complete_list / 2, eval_to_array / 2, eclipse_6 : collection_to_list / 2, lists : collection_to_list / 2, array_list / 2, array_concat / 3, lists : append / 3, is_list / 1, is_array / 1, subscript / 3