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

Source ht_new(--HT)
Create a new hash table.
Source ht_is_hashtable(@HT) is semidet
True when HT is a hash table.
Source ht_size(+HT, -Count) is det
True when Size is the number of key-value pairs in HT.
Source ht_put(!HT, +Key, +Value) is det
Add a Key-Value to HT. The binding is undone on backtracking.
Source 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.
Source 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)
Source 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).
Source 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.
Source ht_get(+HT, +Key, -Value) is semidet
True when Key is in HT and associated with Value.
Source ht_gen(+HT, ?Key, ?Value) is nondet
True when Key-Value is in HT. Pairs are enumerated on backtracking using the hash table order.
Source ht_pairs(?HT, ?Pairs) is det
True when Pairs and HT represent the same association. When used in mode (+,-), Pairs is an ordered set.
Source ht_keys(+HT, -Keys) is det
True when Keys is an ordered set of all keys in HT.