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.

make-hash-table 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.

hashq-ref 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.

hashv-ref 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.

hash-ref 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.

hashq-set! 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.

hashv-set! 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.

hash-set! 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.

hashq-remove! 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.

hashv-remove! 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.

hash-remove! 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 case-insensitive 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.

hashx-ref 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, hashq-ref table key is equivalent to hashx-ref hashq assq table key.

hashx-set! 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, hashq-set! table key is equivalent to hashx-set! hashq assq table key.

hashq-get-handle 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.

hashv-get-handle 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.

hash-get-handle 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.

hashx-get-handle hash assoc table key Scheme Procedure
scm_hashx_get_handle (hash, assoc, table, key) C Function
This behaves the same way as the corresponding -get-handle 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.

hashq-create-handle! 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.

hashv-create-handle! 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.

hash-create-handle! 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.

hashx-create-handle! 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 -create-handle 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.

hash-fold proc init table Scheme Procedure
scm_hash_fold (proc, init, table) C Function
An iterator over hash-table elements. Accumulates and returns a result by applying PROC successively. The arguments to PROC are "(key value prior-result)" where key and value are successive pairs from the hash table TABLE, and prior-result is either INIT (for the first application of PROC) or the return value of the previous application of PROC. For example, (hash-fold acons '() tab) will convert a hash table into an a-list of key-value pairs.