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).

 ht_del(!HT, +Key, -Value) is semidet

Delete Key-Value from HT. Fails if Key does not appear in HT or Value does not unify with the old associated value.

 ht_get(+HT, +Key, -Value) is semidet

True when Key is in HT and associated with Value.

 ht_gen(+HT, ?Key, ?Value) is nondet

True when Key-Value is in HT. Pairs are enumerated on backtracking using the hash table order.

 ht_pairs(?HT, ?Pairs) is det

True when Pairs and HT represent the same association. When used in mode (+,-), Pairs is an ordered set.

 ht_keys(+HT, -Keys) is det

True when Keys is an ordered set of all keys in HT.