Node:Hash Table Reference,
Previous:Hash Table Examples,
Up:Hash Tables
22.7.3.2 Hash Table Reference
Like the association list functions, the hash table functions come
in several varieties: hashq
, hashv
, and hash
.
The hashq
functions use eq?
to determine whether two
keys match. The hashv
functions use eqv?
, and the
hash
functions use equal?
.
In each of the functions that follow, the table argument
must be a vector. The key and value arguments may be
any Scheme object.
makehashtable size

Scheme Procedure 
Create a new hash table of size slots. Note that the number of
slots does not limit the size of the table, it just tells how large
the underlying vector will be. The size should be similar to
the expected number of elements which will be added to the table, but
they need not match. For good performance, it might be a good idea to
use a prime number as the size.

hashqref table key [dflt]

Scheme Procedure 
scm_hashq_ref (table, key, dflt)

C Function 
Look up key in the hash table table, and return the
value (if any) associated with it. If key is not found,
return default (or #f if no default argument
is supplied). Uses eq? for equality testing.

hashvref table key [dflt]

Scheme Procedure 
scm_hashv_ref (table, key, dflt)

C Function 
Look up key in the hash table table, and return the
value (if any) associated with it. If key is not found,
return default (or #f if no default argument
is supplied). Uses eqv? for equality testing.

hashref table key [dflt]

Scheme Procedure 
scm_hash_ref (table, key, dflt)

C Function 
Look up key in the hash table table, and return the
value (if any) associated with it. If key is not found,
return default (or #f if no default argument
is supplied). Uses equal? for equality testing.

hashqset! table key val

Scheme Procedure 
scm_hashq_set_x (table, key, val)

C Function 
Find the entry in table associated with key, and
store value there. Uses eq? for equality testing.

hashvset! table key val

Scheme Procedure 
scm_hashv_set_x (table, key, val)

C Function 
Find the entry in table associated with key, and
store value there. Uses eqv? for equality testing.

hashset! table key val

Scheme Procedure 
scm_hash_set_x (table, key, val)

C Function 
Find the entry in table associated with key, and
store value there. Uses equal? for equality
testing.

hashqremove! table key

Scheme Procedure 
scm_hashq_remove_x (table, key)

C Function 
Remove key (and any value associated with it) from
table. Uses eq? for equality tests.

hashvremove! table key

Scheme Procedure 
scm_hashv_remove_x (table, key)

C Function 
Remove key (and any value associated with it) from
table. Uses eqv? for equality tests.

hashremove! table key

Scheme Procedure 
scm_hash_remove_x (table, key)

C Function 
Remove key (and any value associated with it) from
table. Uses equal? for equality tests.

The standard hash table functions may be too limited for some
applications. For example, you may want a hash table to store
strings in a caseinsensitive manner, so that references to keys
named "foobar", "FOOBAR" and "FooBaR" will all yield the
same item. Guile provides you with extended hash tables
that permit you to specify a hash function and associator function
of your choosing. The functions described in the rest of this section
can be used to implement such custom hash table structures.
If you are unfamiliar with the inner workings of hash tables, then
this facility will probably be a little too abstract for you to
use comfortably. If you are interested in learning more, see an
introductory textbook on data structures or algorithms for an
explanation of how hash tables are implemented.
hashq key size

Scheme Procedure 
scm_hashq (key, size)

C Function 
Determine a hash value for key that is suitable for
lookups in a hash table of size size, where eq? is
used as the equality predicate. The function returns an
integer in the range 0 to size  1. Note that
hashq may use internal addresses. Thus two calls to
hashq where the keys are eq? are not guaranteed to
deliver the same value if the key object gets garbage collected
in between. This can happen, for example with symbols:
(hashq 'foo n) (gc) (hashq 'foo n) may produce two
different values, since foo will be garbage collected.

hashv key size

Scheme Procedure 
scm_hashv (key, size)

C Function 
Determine a hash value for key that is suitable for
lookups in a hash table of size size, where eqv? is
used as the equality predicate. The function returns an
integer in the range 0 to size  1. Note that
(hashv key) may use internal addresses. Thus two calls
to hashv where the keys are eqv? are not guaranteed to
deliver the same value if the key object gets garbage collected
in between. This can happen, for example with symbols:
(hashv 'foo n) (gc) (hashv 'foo n) may produce two
different values, since foo will be garbage collected.

hash key size

Scheme Procedure 
scm_hash (key, size)

C Function 
Determine a hash value for key that is suitable for
lookups in a hash table of size size, where equal?
is used as the equality predicate. The function returns an
integer in the range 0 to size  1.

hashxref hash assoc table key [dflt]

Scheme Procedure 
scm_hashx_ref (hash, assoc, table, key, dflt)

C Function 
This behaves the same way as the corresponding ref
function, but uses hash as a hash function and
assoc to compare keys. hash must be a function
that takes two arguments, a key to be hashed and a table size.
assoc must be an associator function, like assoc ,
assq or assv .
By way of illustration, hashqref table key is
equivalent to hashxref hashq assq table key .

hashxset! hash assoc table key val

Scheme Procedure 
scm_hashx_set_x (hash, assoc, table, key, val)

C Function 
This behaves the same way as the corresponding set!
function, but uses hash as a hash function and
assoc to compare keys. hash must be a function
that takes two arguments, a key to be hashed and a table size.
assoc must be an associator function, like assoc ,
assq or assv .
By way of illustration, hashqset! table key is
equivalent to hashxset! hashq assq table key .

hashqgethandle table key

Scheme Procedure 
scm_hashq_get_handle (table, key)

C Function 
This procedure returns the (key . value) pair from the
hash table table. If table does not hold an
associated value for key, #f is returned.
Uses eq? for equality testing.

hashvgethandle table key

Scheme Procedure 
scm_hashv_get_handle (table, key)

C Function 
This procedure returns the (key . value) pair from the
hash table table. If table does not hold an
associated value for key, #f is returned.
Uses eqv? for equality testing.

hashgethandle table key

Scheme Procedure 
scm_hash_get_handle (table, key)

C Function 
This procedure returns the (key . value) pair from the
hash table table. If table does not hold an
associated value for key, #f is returned.
Uses equal? for equality testing.

hashxgethandle hash assoc table key

Scheme Procedure 
scm_hashx_get_handle (hash, assoc, table, key)

C Function 
This behaves the same way as the corresponding
gethandle function, but uses hash as a hash
function and assoc to compare keys. hash must be
a function that takes two arguments, a key to be hashed and a
table size. assoc must be an associator function, like
assoc , assq or assv .

hashqcreatehandle! table key init

Scheme Procedure 
scm_hashq_create_handle_x (table, key, init)

C Function 
This function looks up key in table and returns its handle.
If key is not already present, a new handle is created which
associates key with init.

hashvcreatehandle! table key init

Scheme Procedure 
scm_hashv_create_handle_x (table, key, init)

C Function 
This function looks up key in table and returns its handle.
If key is not already present, a new handle is created which
associates key with init.

hashcreatehandle! table key init

Scheme Procedure 
scm_hash_create_handle_x (table, key, init)

C Function 
This function looks up key in table and returns its handle.
If key is not already present, a new handle is created which
associates key with init.

hashxcreatehandle! hash assoc table key init

Scheme Procedure 
scm_hashx_create_handle_x (hash, assoc, table, key, init)

C Function 
This behaves the same way as the corresponding
createhandle function, but uses hash as a hash
function and assoc to compare keys. hash must be
a function that takes two arguments, a key to be hashed and a
table size. assoc must be an associator function, like
assoc , assq or assv .

hashfold proc init table

Scheme Procedure 
scm_hash_fold (proc, init, table)

C Function 
An iterator over hashtable elements.
Accumulates and returns a result by applying PROC successively.
The arguments to PROC are "(key value priorresult)" where key
and value are successive pairs from the hash table TABLE, and
priorresult is either INIT (for the first application of PROC)
or the return value of the previous application of PROC.
For example, (hashfold acons '() tab) will convert a hash
table into an alist of keyvalue pairs.
