10.29 Mutable Dictionary Operations—library(mutdict)

Prolog does not have a dictionary type. Instead, one can use, e.g., AVL trees, with logarithmic access time. This package provides operations on mutable dictionaries. Such a mutdict is an unordered collection of items that consist of a key and a value. The only restrictions on items is that the key must be ground. The given mutdict can hold at most one item for any given key. It uses a hash table representation, which admits table lookup in constant time, if there are no hash collisions. Update operations also take constant time, except under some circumstances when the entire table must be copied, in which case such operations take linear time. In addition, the hash function takes time linear in the size of the key, and so simple keys are more efficient than compound terms. A mutdict is a mutable (see ref-lte-mut), the value of which is accessed and modified by the operations of this package. Following are the exported predicates:

is_mutdict(+Dict)

succeeds when Dict is a mutdict.

list_to_mutdict(+Items, -Dict)

unifies Dict with a new mutdict populated by Items, each of which should be of the form Key-Value.

new_mutdict(-Dict)

unifies Dict with a new mutdict.

mutdict_empty(+Dict)

succeeds when Dict is an empty mutdict.

mutdict_size(+Dict, -Size)

unifies Size with the number of elements of the mutdict Dict.

mutdict_gen(+Dict, -Key, -Value)

succeeds when Dict is a mutdict where one item consists of Key and Value. Iterates over all items, but in no specific order.

mutdict_get(+Dict, +Key, -Value)

If there is an item of the mutdict with key Key, then its value is unified with Value. Otherwise, the goal fails.

mutdict_put(+Dict, +Key, +Value)

If there is an item of the mutdict with key Key, then its value is simply replaced by Value; otherwise, adds the item consisting of Key and Value to the given mutdict.

mutdict_update(+Dict, +Key, -OldValue, +NewValue)

If there is an item of the mutdict with key Key, then its value is unified with OldValue and replaced by NewValue. Otherwise, the goal fails.

mutdict_delete(+Dict, +Key)

If there is an item of the mutdict with key Key, then it is deleted; otherwise, the goal merely succeeds.

mutdict_clear(+Dict)

All items are deleted from the mutdict.

mutdict_keys(+Dict, -Keys)

Keys is unified with the list of keys of mutdict. The list comes in no specific order, and is free of duplicates.

mutdict_values(+Dict, -Values)

Values is unified with the list of values of mutdict. The list comes in no specific order, and can contain duplicates.

mutdict_items(+Dict, -Items)

Items is unified with the list of items of mutdict. Each item is of the form Key-Value. The list comes in no specific order, and is free of duplicates.

mutdict_append(+Dict, +DictOrItems)

where DictOrItems should be a mutdict or a list of items. For each item of DictOrItems of the form Key-Value, if there is an item of the mutdict with key Key, then its value is simply replaced by Value; otherwise, the item is added to the given mutdict.