object

# `pairs`

Useful predicates over lists of pairs (key-value terms).

Author: Paulo Moura
Version: 2:1:0
Date: 2022-12-13
Compilation flags:
`static, context_switching_calls`
Dependencies:
(none)
Remarks:

> - Usage: This object can be loaded independently of other entities in the `types` library by using the goal `logtalk_load(types(pairs))`.

Inherited public predicates:
(none)

## Public predicates

### `keys_values/3`

Converts between a list of pairs and lists of keys and values.

Compilation flags:
`static`
Template:
`keys_values(Pairs,Keys,Values)`
Mode and number of proofs:
`keys_values(+list(pair),-list,-list)` - `one`
`keys_values(-list(pair),+list,+list)` - `one`

### `keys/2`

Returns a list of keys from a list of pairs.

Compilation flags:
`static`
Template:
`keys(Pairs,Keys)`
Mode and number of proofs:
`keys(+list(pair),-list)` - `one`

### `key/2`

Enumerates by backtracking all keys from a list of pairs.

Compilation flags:
`static`
Template:
`key(Pairs,Key)`
Mode and number of proofs:
`key(+list(pair),-term)` - `zero_or_more`

### `values/2`

Returns a list of values from a list of pairs.

Compilation flags:
`static`
Template:
`values(Pairs,Values)`
Mode and number of proofs:
`values(+list(pair),-list)` - `one`

### `value/3`

Returns a value addressed by the given path (a key or a list of keys in the case of nested list of pairs). Fails if path does not exist.

Compilation flags:
`static`
Template:
`value(Pairs,Path,Value)`
Mode and number of proofs:
`value(+list(pair),+term,-term)` - `zero_or_one`
`value(+list(pair),+list,-term)` - `zero_or_one`

### `transpose/2`

Transposes a list of pairs by swapping each pair key and value. The relative order of the list elements is kept.

Compilation flags:
`static`
Template:
`transpose(Pairs,TransposedPairs)`
Mode and number of proofs:
`transpose(+list(pair),-list(pair))` - `one`

### `group_sorted_by_key/2`

Groups pairs by key by sorting them and then constructing new pairs by grouping all values for a given key in a list. Keys are compared using equality. Relative order of values per key is kept. Resulting list of pairs is sorted by key.

Compilation flags:
`static`
Template:
`group_sorted_by_key(Pairs,Groups)`
Mode and number of proofs:
`group_sorted_by_key(+list(pair),-list(pair))` - `one`

### `group_consecutive_by_key/2`

Groups pairs by constructing new pairs by grouping all values for consecutive key in a list. Keys are compared using equality. The relative order of the values for the same key is kept.

Compilation flags:
`static`
Template:
`group_consecutive_by_key(Pairs,Groups)`
Mode and number of proofs:
`group_consecutive_by_key(+list(pair),-list(pair))` - `one`

### `group_by_key/2`

Same as the `group_sorted_by_key/2` predicate. Deprecated.

Compilation flags:
`static`
Template:
`group_by_key(Pairs,Groups)`
Mode and number of proofs:
`group_by_key(+list(pair),-list(pair))` - `one`

### `map/3`

Maps a list into pairs using a closure that applies to each list element to compute its key.

Compilation flags:
`static`
Template:
`map(Closure,List,Pairs)`
Meta-predicate template:
`map(2,*,*)`
Mode and number of proofs:
`map(@callable,+list,-list(pair))` - `one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)