keysort(+List1, ?List2)

+List1

List of elements of the form Term-Term.

?List2

List or variable.

Description

List1 is sorted according to the value of the key Key and the result is unified with List2. No sorting is carried out on Value. The sort is stable, i.e. the order of elements with the same key is preserved.

The sort is done according to the standard ordering of terms. See compare/3 for this standard ordering.

Fail Conditions

Resatisfiable

Exceptions

(4) instantiation fault

List1 is not instantiated.

(5) type error

Either List1 or List2 is instantiated, but not to a list of the form Term-Term.

Examples

Success:
      keysort([n-1,4-a],L).     (gives L = [4-a,n-1]]).
      keysort([f(1)-a,[1]-w,7.2-b,"k"-e,n-q],L).
             (gives L = [7.2-b,"k"-e,n-q,f(1)-a,[1]-w]).
      keysort([f(1,2),g(1)],M). (gives M = [f(1,2),g(1)]).
      keysort([g(1,2)-a, f(1,2)-a],M).
             (gives M = [f(1,2)-a,g(1,2)-a]).
      keysort([f(4,3)-a, f(3,4)-b],M).
             (gives M = [f(3,4)-b,f(4,3)-a]).

Fail:
      keysort([n-1,M-a],[n-1,M-a]).

Error:
      keysort(L1,L2).              (Error 4).
      keysort([n-1,m],L).          (Error 5).

See Also