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