#### 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.

Send feedback on this subject.