hashtable.pl -- Hash tables

Hash tables are one of the many key-value representations available to SWI-Prolog.

This module implements a hash table as a mutable and backtrackable data structure. The hash table is implemented as a closed hash table, where the buckets array is implemented using an unbounded arity compound term. Elements in this array are manipulated using setarg/3.

Hash tables allow for any Prolog data types as keys or values, except that the key cannot be a variable. Applications that require a plain variable as key can do so by wrapping all keys in a compound, e.g., k(Var).

 ht_new(--HT)

Create a new hash table.

 ht_is_hashtable(@HT) is semidet

True when HT is a hash table.

 ht_size(+HT, -Count) is det

True when Size is the number of key-value pairs in HT.

 ht_put(!HT, +Key, +Value) is det

Add a Key-Value to HT. The binding is undone on backtracking.

 ht_put_new(!HT, +Key, +Value) is semidet

As ht_put/3, but fails if Key is already in HT instead of updating the associated value.

 ht_update(+HT, +Key, ?Old, +New) is semidet

True when HT holds Key-Old before and Key-New after this call. Note that it is possible to update to a variable and the instantiate this. For example, a word-count update could be implemented as:

update_word_count(HT, Word) :-
    (   ht_update(HT, Word, Old, New)
    ->  New is Old+1
    ;   ht_put(HT, Word, 1)
    ).

 ht_put(!HT, +Key, +Value, +IfNew, -Old) is det

Add Key-Value to HT. Old is unified with the old value associated with Key or, if Key is new, with IfNew. This can be used to bootstrap managing a list of values, e.g.

ht_put_list(HT, Key, Value) :-
    ht_put(HT, Key, [Value|Tail], [], Tail).

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 ht_keys(Arg1, Arg2)

 ht_pairs(Arg1, Arg2)

 ht_gen(Arg1, Arg2, Arg3)

 ht_del(Arg1, Arg2, Arg3)

 ht_get(Arg1, Arg2, Arg3)