11.3.109 keysort/2   [ISO]

Synopsis

keysort(+Pairs, -Sorted)

Sorts the elements of the list Pairs into ascending standard order (see ref-lte-cte-sot) with respect to the key of the pair structure.

Arguments

Pairs

list of pair, must be a proper list of proper pairs

Sorted

list of pair

Description

The list Pairs must consist of terms of the form Key-Value. Multiple occurrences of pairs with the same key are not removed.

(The time taken to do this is at worst order (N log N) where N is the length of the list.)

Note that the elements of Pairs are sorted only according to the value of Key, not according to the value of Value.

keysort/2 is stable in the sense that the relative position of elements with the same key is maintained.

Sorted is type checked since release 4.3 for alignment with the ISO Prolog standard. Previous releases simply failed instead of reporting an error for malformed Sorted.

Exceptions

instantiation_error

If Pairs is not properly instantiated

type_error

If Pairs is not a proper list of pair.

type_error

If Sorted cannot be unified with a list of pair.

Examples

     | ?- keysort([3-a,1-b,2-c,1-a,1-b], X).
     
     X = [1-b,1-a,1-b,2-c,3-a]

     |?- keysort([2-1, 1-2], [1-2, 2-1]).
     
     yes

See Also

ref-lte-cte-sor.