.. index:: single: dictionaryp
.. _dictionaryp/0:

.. rst-class:: right

**protocol**

``dictionaryp``
===============

Dictionary protocol.

| **Availability:** 
|    ``logtalk_load(dictionaries(loader))``

| **Author:** Paulo Moura
| **Version:** 2:4:0
| **Date:** 2024-10-02

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**
|    (none)

| **Inherited public predicates:**
|    (none)

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

Public predicates
-----------------

.. index:: as_dictionary/2
.. _dictionaryp/0::as_dictionary/2:

``as_dictionary/2``
^^^^^^^^^^^^^^^^^^^

Converts a list of key-value pairs to a dictionary.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``as_dictionary(Pairs,Dictionary)``
| **Mode and number of proofs:**
|    ``as_dictionary(@list(pairs),-dictionary)`` - ``one``


------------

.. index:: as_list/2
.. _dictionaryp/0::as_list/2:

``as_list/2``
^^^^^^^^^^^^^

Converts a dictionary to an ordered list (as per standard order) of key-value pairs.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``as_list(Dictionary,Pairs)``
| **Mode and number of proofs:**
|    ``as_list(@dictionary,-list(pairs))`` - ``one``


------------

.. index:: as_curly_bracketed/2
.. _dictionaryp/0::as_curly_bracketed/2:

``as_curly_bracketed/2``
^^^^^^^^^^^^^^^^^^^^^^^^

Creates a curly-bracketed term representation of a dictionary.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``as_curly_bracketed(Dictionary,Term)``
| **Mode and number of proofs:**
|    ``as_curly_bracketed(+dictionary,--term)`` - ``one``


------------

.. index:: clone/3
.. _dictionaryp/0::clone/3:

``clone/3``
^^^^^^^^^^^

Clones a dictionary using the same keys but with all values unbound and returning a list of all the pairs in the new clone.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``clone(Dictionary,Clone,ClonePairs)``
| **Mode and number of proofs:**
|    ``clone(+dictionary,-dictionary,-list(pairs))`` - ``one``


------------

.. index:: clone/4
.. _dictionaryp/0::clone/4:

``clone/4``
^^^^^^^^^^^

Clones a dictionary using the same keys but with all values unbound and returning the list of all pairs in the dictionary and in the clone.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``clone(Dictionary,Pairs,Clone,ClonePairs)``
| **Mode and number of proofs:**
|    ``clone(+dictionary,-list(pairs),-dictionary,-list(pairs))`` - ``one``


------------

.. index:: insert/4
.. _dictionaryp/0::insert/4:

``insert/4``
^^^^^^^^^^^^

Inserts a key-value pair into a dictionary, returning the updated dictionary. When the key already exists, the associated value is updated.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``insert(OldDictionary,Key,Value,NewDictionary)``
| **Mode and number of proofs:**
|    ``insert(+dictionary,+ground,@term,-dictionary)`` - ``one``


------------

.. index:: delete/4
.. _dictionaryp/0::delete/4:

``delete/4``
^^^^^^^^^^^^

Deletes a matching key-value pair from a dictionary, returning the updated dictionary. Fails if it cannot find the key or if the key exists but the value does not unify.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``delete(OldDictionary,Key,Value,NewDictionary)``
| **Mode and number of proofs:**
|    ``delete(+dictionary,@ground,?term,-dictionary)`` - ``zero_or_one``


------------

.. index:: update/4
.. _dictionaryp/0::update/4:

``update/4``
^^^^^^^^^^^^

Updates the value associated with Key in a dictionary, returning the updated dictionary. Fails if it cannot find the key.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``update(OldDictionary,Key,NewValue,NewDictionary)``
| **Mode and number of proofs:**
|    ``update(+dictionary,@ground,+term,-dictionary)`` - ``zero_or_one``


------------

.. index:: update/5
.. _dictionaryp/0::update/5:

``update/5``
^^^^^^^^^^^^

Updates the value associated with a key in a dictionary, returning the updated dictionary. Fails if it cannot find the key or if the existing value does not unify.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``update(OldDictionary,Key,OldValue,NewValue,NewDictionary)``
| **Mode and number of proofs:**
|    ``update(+dictionary,@ground,?term,+term,-dictionary)`` - ``zero_or_one``


------------

.. index:: update/3
.. _dictionaryp/0::update/3:

``update/3``
^^^^^^^^^^^^

Updates the key-value pairs in a dictionary, returning the updated dictionary. Fails if it cannot find one of the keys.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``update(OldDictionary,Pairs,NewDictionary)``
| **Mode and number of proofs:**
|    ``update(+dictionary,@list(pair),-dictionary)`` - ``zero_or_one``


------------

.. index:: empty/1
.. _dictionaryp/0::empty/1:

``empty/1``
^^^^^^^^^^^

True iff the dictionary is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``empty(Dictionary)``
| **Mode and number of proofs:**
|    ``empty(@dictionary)`` - ``zero_or_one``


------------

.. index:: lookup/3
.. _dictionaryp/0::lookup/3:

``lookup/3``
^^^^^^^^^^^^

Lookups a matching key-value pair from a dictionary. Fails if no match is found.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lookup(Key,Value,Dictionary)``
| **Mode and number of proofs:**
|    ``lookup(+ground,?term,@dictionary)`` - ``zero_or_one``
|    ``lookup(-ground,?term,@dictionary)`` - ``zero_or_more``


------------

.. index:: lookup/2
.. _dictionaryp/0::lookup/2:

``lookup/2``
^^^^^^^^^^^^

Lookups all matching key-value pairs from a dictionary. Fails if it cannot find one of the keys or if a value for a key does not unify.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``lookup(Pairs,Dictionary)``
| **Mode and number of proofs:**
|    ``lookup(+list(pair),@dictionary)`` - ``zero_or_one``


------------

.. index:: intersection/2
.. _dictionaryp/0::intersection/2:

``intersection/2``
^^^^^^^^^^^^^^^^^^

True iff the values of the dictionaries common keys unify. Trivially true when there are no common keys.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``intersection(Dictionary1,Dictionary2)``
| **Mode and number of proofs:**
|    ``intersection(+dictionary,+dictionary)`` - ``zero_or_one``


------------

.. index:: intersection/3
.. _dictionaryp/0::intersection/3:

``intersection/3``
^^^^^^^^^^^^^^^^^^

Returns the (possibly empty) intersection between two dictionaries when the values of their common keys unify.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``intersection(Dictionary1,Dictionary2,Intersection)``
| **Mode and number of proofs:**
|    ``intersection(+dictionary,+dictionary,-dictionary)`` - ``zero_or_one``


------------

.. index:: previous/4
.. _dictionaryp/0::previous/4:

``previous/4``
^^^^^^^^^^^^^^

Returns the previous pair in a dictionary given a key. Fails if there is no previous pair.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``previous(Dictionary,Key,Previous,Value)``
| **Mode and number of proofs:**
|    ``previous(+dictionary,+key,-key,-value)`` - ``zero_or_one``


------------

.. index:: next/4
.. _dictionaryp/0::next/4:

``next/4``
^^^^^^^^^^

Returns the next pair in a dictionary given a key. Fails if there is no next pair.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``next(Dictionary,Key,Next,Value)``
| **Mode and number of proofs:**
|    ``next(+dictionary,+key,-key,-value)`` - ``zero_or_one``


------------

.. index:: min/3
.. _dictionaryp/0::min/3:

``min/3``
^^^^^^^^^

Returns the pair with the minimum key (as per standard order) in a dictionary. Fails if the dictionary is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``min(Dictionary,Key,Value)``
| **Mode and number of proofs:**
|    ``min(+dictionary,-key,-value)`` - ``zero_or_one``


------------

.. index:: max/3
.. _dictionaryp/0::max/3:

``max/3``
^^^^^^^^^

Returns the pair with the maximum key (as per standard order) in a dictionary. Fails if the dictionary is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``max(Dictionary,Key,Value)``
| **Mode and number of proofs:**
|    ``max(+dictionary,-key,-value)`` - ``zero_or_one``


------------

.. index:: delete_min/4
.. _dictionaryp/0::delete_min/4:

``delete_min/4``
^^^^^^^^^^^^^^^^

Deletes the pair with the minimum key (as per standard order) from a dictionary, returning the deleted pair and the updated dictionary. Fails if the dictionary is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``delete_min(OldDictionary,Key,Value,NewDictionary)``
| **Mode and number of proofs:**
|    ``delete_min(+dictionary,-key,-value,-dictionary)`` - ``zero_or_one``


------------

.. index:: delete_max/4
.. _dictionaryp/0::delete_max/4:

``delete_max/4``
^^^^^^^^^^^^^^^^

Deletes the pair with the maximum key (as per standard order) from a dictionary, returning the deleted pair and the updated dictionary. Fails if the dictionary is empty.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``delete_max(OldDictionary,Key,Value,NewDictionary)``
| **Mode and number of proofs:**
|    ``delete_max(+dictionary,-key,-value,-dictionary)`` - ``zero_or_one``


------------

.. index:: keys/2
.. _dictionaryp/0::keys/2:

``keys/2``
^^^^^^^^^^

Returns a list with all the dictionary keys in ascending order (as per standard order).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``keys(Dictionary,Keys)``
| **Mode and number of proofs:**
|    ``keys(@dictionary,-list)`` - ``one``


------------

.. index:: values/2
.. _dictionaryp/0::values/2:

``values/2``
^^^^^^^^^^^^

Returns a list with all the dictionary values in ascending order of the keys (as per standard order).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``values(Dictionary,Values)``
| **Mode and number of proofs:**
|    ``values(@dictionary,-list)`` - ``one``


------------

.. index:: map/2
.. _dictionaryp/0::map/2:

``map/2``
^^^^^^^^^

Maps a closure over each dictionary key-value pair. Fails if the mapped closure attempts to modify the keys.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``map(Closure,Dictionary)``
| **Meta-predicate template:**
|    ``map(1,*)``
| **Mode and number of proofs:**
|    ``map(@callable,+dictionary)`` - ``zero_or_more``


------------

.. index:: map/3
.. _dictionaryp/0::map/3:

``map/3``
^^^^^^^^^

Maps a closure over each dictionary key-value pair, returning the new dictionary. Fails if the mapped closure attempts to modify the keys.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``map(Closure,OldDictionary,NewDictionary)``
| **Meta-predicate template:**
|    ``map(2,*,*)``
| **Mode and number of proofs:**
|    ``map(@callable,+dictionary,-dictionary)`` - ``zero_or_more``


------------

.. index:: apply/4
.. _dictionaryp/0::apply/4:

``apply/4``
^^^^^^^^^^^

Applies a closure to a specific key-value pair, returning the new dictionary. Fails if the key cannot be found or if the mapped closure attempts to modify the key.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``apply(Closure,OldDictionary,Key,NewDictionary)``
| **Meta-predicate template:**
|    ``apply(2,*,*,*)``
| **Mode and number of proofs:**
|    ``apply(+callable,+dictionary,+key,-dictionary)`` - ``zero_or_one``


------------

.. index:: size/2
.. _dictionaryp/0::size/2:

``size/2``
^^^^^^^^^^

Number of dictionary entries.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``size(Dictionary,Size)``
| **Mode and number of proofs:**
|    ``size(@dictionary,?integer)`` - ``one``


------------

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)

.. seealso::

   :ref:`avltree <avltree/0>`, :ref:`bintree <bintree/0>`, :ref:`rbtree <rbtree/0>`

