Both variants of the hashtbl library share a common data representation: A
hash table is a term nb_hashtbl/2 or p_hashtbl/2. The first argument
contains metadata such as the hash table's current load. The second is a
term bucket/N containing the hash buckets. Hash buckets are lists of
Key-Values pairs where Key is a hash table key (a ground term) and Values is
the list of Values associated with that key. Each key only occurs once in
the table. When several values are added for the same key, later ones come
before the older ones in the Values list. They have "higher priority" and
are said to "shadow" the older values.
Due to this common representation of hash tables, many operations are
identical on the two variants, differing only in the outermost functor.
These non-destructive common operations, such as getting values from the
table, or mapping higher-order predicates over the table, are defined in
The concrete implementations of the hash tables use the predicates from this
module. This is the only intended use of this module: It should be treated
as internal to the library. Clients of the library should use one of the
concrete hash table modules.
- - Gergö Barany <firstname.lastname@example.org>
- - LGPL
- hashtbl_default_size(-N) is det
- N is the default number of buckets in a newly created hash table.
- hashtbl_bucket(+Table, +Key, -BucketTerm, -BucketIdx, -Bucket) is det
- Finds the hash bucket in Table for the given Key. BucketTerm is the
Table's term holding the hash buckets, BucketIdx is the argument index
into the BucketTerm (as for arg/3) of the hash bucket corresponding to
the Key, and Bucket is the corresponding hash bucket. Always succeeds,
even if Key is not in the Table.
- hashtbl_load(+Table, -Load) is det
- Load is the current number of keys stored in Table.
- hashtbl_buckets(+Table, -Buckets) is det
- Buckets is the number of hash buckets in Table.
- 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
nb_hashtbl_get(Table, Key, _) to test whether Key is
present in Table.
- 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.
- 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
hashtbl_get_all/3. The ordering is otherwise unspecified.
If Key is ground, this behaves like hashtbl_get_all/3 for that Key.
However, hashtbl_get_all/3 is more efficient in this case.
- 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.
- key_value_cons(?Key, ?Value, ?Acc, ?List) is det
- List is a list with head Key-Value and tail Acc.
- 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,
hashtbl_map/3 enumerates several TableOut tables accordingly.
- hashtbl_fold(+Table, :Goal, +Acc, -Result) is nondet
- Folds Goal over every Key and Value in the Table. Calls
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.
- hashtbl_iter(+Table, :Goal) is nondet
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.