[ Comparing and Sorting | Reference Manual | Alphabetic Index ]

# 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.

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.

## 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) instantiation fault
  Numeric order is selected, but Random contains variables
(5) type error
  Key is greater than 0, and not all of Random's elements are compound terms.
(5) type error
  Key is not an integer or a list of integers.
(5) type error
  Numeric order is selected, but Random contains non-numeric elements.
(6) out of range
  One of the compound terms in Random has not got as many as Key arguments.
(20) arithmetic exception
  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