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

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