
eval_to_array(?Collection, ?Result)

   Equate a "collection" expression with an array

Arguments
   Collection          A term to be interpreted as a collection
   Result              The collection as array

Type
   Term Manipulation

Description
   This is a constraint establishing equality between a collection-valued
   expression and an array 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 converted into an array, as with array_list/2.
   Array
	The array is returned unchanged.

   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_array(?, ?) 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_array(List, Result).
   Result = [](a, b, c, d)

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

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


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

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

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

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

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

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

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

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


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

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

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

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


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


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

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

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


   % Cases with insufficient instantiation:

   ?- eval_to_array(Xs, R).
   R = R
   <delays until Xs (or R) instantiated>

   ?- eval_to_array([1|Xs], R).
   R = R
   <delays until Xs instantiated>

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

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

   ?- eval_to_array(Xs>>[3], R), Xs=[1].
   R = [](1,2)
   Yes

   ?- eval_to_array([1]>>Ys, R).
   R = R
   <delays until Ys instantiated>

   ?- eval_to_array([1]>>Ys, R), Ys=[2].
   R = [](1,2)
   Yes

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


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

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

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


   % Reverse direction
   ?- eval_to_array(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
