.. index:: pairs .. _pairs/0:

.. rst-class:: right

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)

.. contents:: :local: :backlinks: top

Public predicates

.. index:: keys_values/3 .. _pairs/0::keys_values/3:

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

---

.. index:: keys/2 .. _pairs/0::keys/2:

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

---

.. index:: key/2 .. _pairs/0::key/2:

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

---

.. index:: values/2 .. _pairs/0::values/2:

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

---

.. index:: value/3 .. _pairs/0::value/3:

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

---

.. index:: transpose/2 .. _pairs/0::transpose/2:

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

---

.. index:: group_sorted_by_key/2 .. _pairs/0::group_sorted_by_key/2:

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

---

.. index:: group_consecutive_by_key/2 .. _pairs/0::group_consecutive_by_key/2:

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

---

.. index:: group_by_key/2 .. _pairs/0::group_by_key/2:

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

---

.. index:: map/3 .. _pairs/0::map/3:

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)