object

# `pairs`

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

Availability:
`logtalk_load(types(loader))`
Author: Paulo Moura
Version: 2:1:1
Date: 2023-11-21
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. When converting to pairs, this predicate fails if the list of keys and the list of values have different lengths.

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)` - `zero_or_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)