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

.. rst-class:: right

**protocol**

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

Dictionary protocol.

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

| **Author:** Paulo Moura
| **Version:** 2:6:0
| **Date:** 2026-02-10

| **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/4
.. _dictionaryp/0::lookup/4:

``lookup/4``
^^^^^^^^^^^^

Lookups a matching key-value pair from a dictionary and returns the splayed dictionary with the key at the root. Fails if the key is not found. In implementations that do not update the dictionary on lookup, the same dictionary is returned.

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

| **Template:**
|    ``lookup(Key,Value,Dictionary,SplayedDictionary)``
| **Mode and number of proofs:**
|    ``lookup(+ground,?term,+tree,-tree)`` - ``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>`, :ref:`splaytree <splaytree/0>`

