[ Comparing and Sorting | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# number_sort(+Key, +Order, +Random, -Sorted)

Succeeds if Sorted is the numerically sorted list 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 >=.
Random
  List.
Sorted
  List or variable.

## Description

Sorts the list Random according to the Key and Order specifications, and unifies Sorted with the result. The sort is stable, i.e. the order of elements with the same key is preserved.

If Random is not a list of compound terms, use Key = 0. The list elements must be numerical terms.

If Random is a list of compound terms, then the sort will be according to the Keyth argument of the list elements. The Keyth argument of each list element must be a numeric term.

In all cases, Order specifies whether the list is sorted into ascending (<, =<) or descending (>, >=) order and whether duplicates are to be retained (=<, >=) or eliminated (<, >). The way to remember the Order argument is that it is the relation which holds between adjacent elements in the result.

The sort is done according to numerical ordering as opposed to sort/4 which uses the standard ordering of terms. See compare/3 for this standard ordering. In particular for numeric terms of different type, e.g. integers and floats, the numerical and standard orderings differ: 1 < 2.0 but 2.0 @< 1. Additionally the ordering of bounded reals differs. While the standard ordering treats a bounded real as a compound term and orders them by lower bound and then upper bound, numerical ordering treats them as true intervals. As a consequence the order of overlapping intervals is undefined: 1.0__1.1 @< 1.0__1.2 while no numerical order is defined. In such cases an arithmetic exception is thrown. This can have unexpected consequences: care must be taken when sorting a list containing both rationals and bounded reals. While integers and floats are converted to zero-width intervals for the purposes of comparison, rationals are converted to small intervals guaranteed to contain the rational, e.g X is breal(1_1) gives X=0.99999999999999989__1.0000000000000002 and thus no order is defined between 1_1 and 1.0__1.0.

### Modes and Determinism

- number_sort(+, +, +, -) is det

### Exceptions

(4) instantiation fault
  One of List1 and List2 has an element whose Keyth argument is a variable
(5) type error
  Key is greater than 0, and one of List1 and List2 has an element whose Keyth argument is a non-numeric term
(5) type error
  Key is greater than 0, and one of List1 and List2 does not have all elements 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 List1 or List2 has not got as many as Key arguments.
(20) arithmetic exception
  One of List1 and List2 has elements whose numerical order is undefined.

## Examples

    Success:
          number_sort(0,<,[3,1,6,7,2],S).             (gives S=[1,2,3,6,7]).
          number_sort(0,=<,[1,1.0,1_1,3,2,3,4,1],S).
    			   (gives S=[1,1.0,1_1,1,2,3,3,4]).
          number_sort(0,=<,[1,1.0,1.0__1.0,3,2,3,4,1],S).
    			   (gives S=[1,1.0,1.0__1.0,1,2,3,3,4]).
          number_sort(2,<,[f(a,3),h(b,1)],S).         (gives S=[h(2,1),f(1,3)]).
          number_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))]).

    Fail:
          number_sort(0,<,[2,1,3,4],[2,1,3,4]).

    Error:
          number_sort(0,>,[1,3,N],S).              (Error 4).
          number_sort(0,>,[q,1,3,a,e],S).          (Error 5).
          number_sort(1,<,[f(1),f(3),5],S).        (Error 5).
          number_sort(1.0,<,[f(1),f(3),f(5)],S).   (Error 5).
          number_sort(1,<,[f(a,3),h(b,1)],S).      (Error 5).
          number_sort(2,<,[f(1,2),g(3,1),f(5)],S). (Error 6).
          number_sort(0,<,[1,0.9__1.1],S).         (Error 20).
          number_sort(0,=<,[1_1,1.0__1.0],S).      (Error 20).

## See Also

compare / 3, number_sort / 2, sort / 2, sort / 4