
array_sort(+Key, +Order, +Random, -Sorted)

   Succeeds if Sorted is the sorted version of Random.  The sort is done
according to the Key and Order specifications.

Arguments
   Key                 A non-negative integer, or a list of positive integers.
   Order               One of the atoms =<, >=, < or >, possibly prefixed with @ or $.
   Random              Array.
   Sorted              Array or variable.

Type
   Comparing and Sorting

Description
   Generic sorting primitive: sorts the array Random according to the Key
   and Order specifications, and unifies Sorted with the resulting array.

   This predicate is identical to sort/4, except that it sorts arrays
   instead of lists.  See sort/4 for the details.



Modes and Determinism
   array_sort(+, +, +, -) is det

Exceptions
     4 --- Numeric order is selected, but Random contains variables
     5 --- Key is greater than 0, and not all of Random's elements are compound terms.
     5 --- Key is not an integer or a list of integers.
     5 --- Numeric order is selected, but Random contains non-numeric elements.
     6 --- One of the compound terms in Random has not got as many as Key arguments.
    20 --- Random has elements whose numerical order is undefined.

Examples
   
Success:
      array_sort(0, <, [],     S).              (gives S=[]).
      array_sort(0, <, [](3,1,6,7,2),     S).   (gives S=[](1,2,3,6,7)).
      array_sort(0, >, [](q,1,3,a,e,N),   S).   (gives N=_g78,S=[](q,e,a,3,1,_g78)).
      array_sort(0,=<, [](1,3,2,3,4,1),   S).   (gives S=[](1,1,2,3,3,4)).
      array_sort(2, <, [](f(1,3),h(2,1)), S).   (gives S=[](h(2,1),f(1,3))).
      array_sort(1, <, [](f(1,3),h(2,1)), S).   (gives S=[](f(1,3),h(2,1))).

      array_sort([2,1], =<, [](f(3,a(2)),f(1,a(1)),f(0,a(3)),f(1,a(4))), S).
		       (gives S=[](f(1,a(1)),f(3,a(2)),f(0,a(3)),f(1,a(4)))).

   % standard vs numeric order
      array_sort(0, @<, [](1,2,3,2.0,3), S).  (gives S = [](2.0, 1, 2, 3))
      array_sort(0, $<, [](1,2,3,2.0,3), S).  (gives S = [](1, 2, 3))

      array_sort(0,@=<, [](1,2,3,2.0,3), S).  (gives S = [](2.0, 1, 2, 3, 3))
      array_sort(0,$=<, [](1,2,3,2.0,3), S).  (gives S = [](1, 2, 2.0, 3, 3))

      array_sort(0,@=<, [](1,1.0,1_1), S).    (gives S = [](1.0, 1_1, 1))
      array_sort(0,$=<, [](1,1.0,1_1), S).    (gives S = [](1, 1.0, 1_1))

      array_sort(0, @<, [](1,1.0,1_1), S).    (gives S = [](1.0, 1_1, 1))
      array_sort(0, $<, [](1,1.0,1_1), S).    (gives S = [](1))
      array_sort(0, $<, [](1.0,1,1_1), S).    (gives S = [](1.0))
      array_sort(0, $<, [](1_1,1.0,1), S).    (gives S = [](1_1))

   % Sort according to argument 3 (major) and 2 (minor) - method 1
      ?- S = [](t(ok,a,2), t(good,b,1), t(best,a,1)),
 	array_sort(2, =<, S, S2),           % sort less important key first
  	array_sort(3, =<, S2, S32).         % sort more important key last
 
      S2 = [](t(ok,a,2), t(best,a,1), t(good,b,1))
      S32 = [](t(best,a,1), t(good,b,1), t(ok,a,2))
      Yes (0.00s cpu)

   % Sort according to argument 3 (major) and 2 (minor) - method 2
     ?-  S = [](t(ok,a,2), t(good,b,1), t(best,a,1)),
	( foreach(T,S),foreach(K-T,KTs) do T=t(_,B,C), K=key(C,B) ),
	array_sort(1, =<, KTs, SKTs),       % same as keysort(KTs, SKTs)
	( foreach(_-T,SKTs), foreach(T,S32) do true ).

     KTs = [](key(2,a)-t(ok,a,2), key(1,b)-t(good,b,1), key(1,a)-t(best,a,1))
     SKTs = [](key(1,a)-t(best,a,1), key(1,b)-t(good,b,1), key(2,a)-t(ok,a,2))
     S32 = [](t(best,a,1), t(good,b,1), t(ok,a,2))
     Yes (0.00s cpu)


Error:
      array_sort(0,   <, [5,6,2], S).                (Error 5).
      array_sort(1,   <, [](f(1),f(3),5), S).        (Error 5).
      array_sort(1.0, <, [](f(1),f(3),f(5)), S).     (Error 5).
      array_sort(2,   <, [](f(1,2),g(3,a),f(5)), S). (Error 6).
      array_sort(0,  $<, [](1,two,3), S).            (Error 5).
      array_sort(0,  $<, [](1.0__1.1,1.0__1.1), S).  (Error 20).


See Also
   compare / 3, sort / 4
