.. 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 `, :ref:`bintree `, :ref:`rbtree `