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)

## Public predicates

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `empty/1`

True iff the dictionary is empty.

Compilation flags:
`static`
Template:
`empty(Dictionary)`
Mode and number of proofs:
`empty(@dictionary)` - `zero_or_one`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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`

### `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)

See also

avltree, bintree, rbtree