This module defines impure (imperative) hash tables that allow destructive
updates.
The predicates in this module use destructive non-backtrackable updates to
implement the hash table. The basic operation used internally to implement
changes to the hash table is nb_linkarg/3. Use with care.
The user should take care never to copy a non-backtrackable hash table. This
includes never using asserta/1 or assertz/1 to store it in the database. If
the table is to be stored in a global variable, nb_linkval/2 should be used
for the purpose.
- author
- - GergĂ¶ Barany <gergo@tud.at>
- license
- - LGPL
- empty_nb_hashtbl(-Table) is det
- Unifies Table with a newly created empty hash table of a default size.
- empty_nb_hashtbl(-Table, +Size) is det
- Unifies Table with a newly created empty hash table with the number of
buckets given by Size.
- throws
- - Type or domain error if Size is not a non-negative integer.
- nb_hashtbl_put(!Table, +Key, +Value) is det
- Puts the Value into the Table at Key. If there are already values stored
for Key, this new value will shadow them until it is deleted from the
table.
- nb_hashtbl_set(!Table, +Key, +Value) is det
- Sets the Value associated with Key in Table. If there are already values
stored for Key in Table, the most recent one will is overwritten. If that
entry shadowed earlier entries for Key, those remain shadowed and
unchanged.
- nb_hashtbl_get(+Table, +Key, -Value) is semidet
- Gets the most recently stored Value for Key in Table, if any. Fails if no
values are stored for Key. There is no separate predicate for membership
checks, use
nb_hashtbl_get(Table, Key, _)
to test whether Key is
present in Table.
- nb_hashtbl_get_all(+Table, +Key, -Value) is nondet
- On backtracking, enumerates every Value associated with Key in Table.
Fails if no values are stored for Key. The order of enumeration is the
most recently added value for Key first (the same as the solution for
nb_hashtbl_get/3), then shadowed ones.
- nb_hashtbl_get_default(!Table, +Key, ?Default, -Value) is det
- If Table contains an entry for Key, unifies Value with the corresponding
value as in nb_hashtbl_get/3. Otherwise, unifies Value with Default and
adds this value to the Table under Key.
- nb_hashtbl_delete(!Table, +Key) is det
- Deletes the most recent value stored under Key in Table, if any. Does
nothing otherwise; succeeds always.
- nb_hashtbl_enumerate(+Table, -Key, -Value) is nondet
- On backtracking, enumerates every Key-Value pair stored in the Table.
Fails if the table is empty. If several values are stored for the same
key, their order of enumeration is most recent first, as in
nb_hashtbl_get_all/3. The ordering is otherwise unspecified.
If Key is ground, this behaves like nb_hashtbl_get_all/3 for that Key.
However, nb_hashtbl_get_all/3 is more efficient in this case.
- nb_hashtbl_to_list(+Table, -Pairs) is det
- Unifies Pairs with a list of all Key-Value pairs in the order as
enumerated by nb_hashtbl_enumerate/3.
- list_to_nb_hashtbl(+Pairs, -Table) is semidet
- If Pairs is a list of Key-Value pairs, unifies Table with a corresponding
hash table of a default size containing all those pairs. If there are
several entries for the same Key in the list, later entries will shadow
earlier ones in the Table.
- list_to_nb_hashtbl(+Pairs, -Table, +Size) is semidet
- As list_to_nb_hashtbl/2, but the hash table has an initial number of
buckets given by Size.
- throws
- - Type or domain error if Size is not a non-negative integer.
- nb_hashtbl_map(+Table, :Goal, -TableOut) is nondet
- For every Key and Value in Table, calls
Goal(Key, Value, Value1)
and
unifies TableOut with a hash table containing all Key-Value1 pairs.
Deterministic if Goal is deterministic. If Goal backtracks,
nb_hashtbl_map/3 enumerates several TableOut tables accordingly.
- nb_hashtbl_fold(+Table, :Goal, +Acc, -Result) is nondet
- Folds Goal over every Key and Value in the Table. Calls
Goal(Key,
Value, Acc, Result)
, using each call's Result as the next call's
accumulator Acc, and unifying Result with the final call's Result.
Deterministic if Goal is deterministic. If Goal backtracks, enumerates
several results accordingly.
- nb_hashtbl_iter(+Table, :Goal) is nondet
- Calls
Goal(Key, Value)
for every Key and Value stored in Table. This
is useful to ensure that all entries satisfy some predicate, or for
Goal's side effects. Deterministic if Goal is deterministic.
- nb_hashtbl_unfold(:Goal, -Table) is det
- Unfolds the binary goal Goal into the Table: Unifies Table with a hash
table containing a Key-Value entry for every solution of
Goal(Key,
Value)
. Table is empty if Goal has no solutions. Later solutions of
Goal will shadow earlier ones in Table.