[ 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

(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.
(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).
```