Like the association list functions, the hash table functions come in
several varieties, according to the equality test used for the keys.
Plain `hash-`

functions use `equal?`

, `hashq-`

functions use `eq?`

, `hashv-`

functions use `eqv?`

, and
the `hashx-`

functions use an application supplied test.

A single `make-hash-table`

creates a hash table suitable for use
with any set of functions, but it's imperative that just one set is
then used consistently, or results will be unpredictable.

Hash tables are implemented as a vector indexed by a hash value formed
from the key, with an association list of key/value pairs for each
bucket in case distinct keys hash together. Direct access to the
pairs in those lists is provided by the `-handle-`

functions.
The abstract kind of hash tables hide the vector in an opaque object
that represents the hash table, while for the concrete kind the vector
*is* the hashtable.

When the number of table entries in an abstract hash table goes above a threshold, the vector is made larger and the entries are rehashed, to prevent the bucket lists from becoming too long and slowing down accesses. When the number of entries goes below a threshold, the vector is shrunk to save space.

A abstract hash table is created with `make-hash-table`

. To
create a vector that is suitable as a hash table, use
`(make-vector `

`size`` '())`

, for example.

For the `hashx-`

“extended” routines, an application supplies a
`hash` function producing an integer index like `hashq`

etc
below, and an `assoc` alist search function like `assq`

etc
(see Retrieving Alist Entries). Here's an example of such
functions implementing case-insensitive hashing of string keys,

(use-modules (srfi srfi-1) (srfi srfi-13)) (define (my-hash str size) (remainder (string-hash-ci str) size)) (define (my-assoc str alist) (find (lambda (pair) (string-ci=? str (car pair))) alist)) (define my-table (make-hash-table)) (hashx-set! my-hash my-assoc my-table "foo" 123) (hashx-ref my-hash my-assoc my-table "FOO") ⇒ 123

In a `hashx-`

`hash` function the aim is to spread keys
across the vector, so bucket lists don't become long. But the actual
values are arbitrary as long as they're in the range 0 to
`size`-1. Helpful functions for forming a hash value, in
addition to `hashq`

etc below, include `symbol-hash`

(see Symbol Keys), `string-hash`

and `string-hash-ci`

(see String Comparison), and `char-set-hash`

(see Character Set Predicates/Comparison).

— Scheme Procedure: **make-hash-table** [`size`]

Create a new abstract hash table object, with an optional minimum vector

size.When

sizeis given, the table vector will still grow and shrink automatically, as described above, but withsizeas a minimum. If an application knows roughly how many entries the table will hold then it can usesizeto avoid rehashing when initial entries are added.

— Scheme Procedure: **hash-table?**` obj`

— C Function:**scm_hash_table_p** (`obj`)

— C Function:

Return

`#t`

ifobjis a abstract hash table object.

— Scheme Procedure: **hash-clear!**` table`

— C Function:**scm_hash_clear_x** (`table`)

— C Function:

Remove all items from

table(without triggering a resize).

— Scheme Procedure: **hash-ref**` table key `[`dflt`]

— Scheme Procedure:**hashq-ref**` table key `[`dflt`]

— Scheme Procedure:**hashv-ref**` table key `[`dflt`]

— Scheme Procedure:**hashx-ref**` hash assoc table key `[`dflt`]

— C Function:**scm_hash_ref** (`table, key, dflt`)

— C Function:**scm_hashq_ref** (`table, key, dflt`)

— C Function:**scm_hashv_ref** (`table, key, dflt`)

— C Function:**scm_hashx_ref** (`hash, assoc, table, key, dflt`)

— Scheme Procedure:

— Scheme Procedure:

— Scheme Procedure:

— C Function:

— C Function:

— C Function:

— C Function:

Lookup

keyin the given hashtable, and return the associated value. Ifkeyis not found, returndflt, or`#f`

ifdfltis not given.

— Scheme Procedure: **hash-set!**` table key val`

— Scheme Procedure:**hashq-set!**` table key val`

— Scheme Procedure:**hashv-set!**` table key val`

— Scheme Procedure:**hashx-set!**` hash assoc table key val`

— C Function:**scm_hash_set_x** (`table, key, val`)

— C Function:**scm_hashq_set_x** (`table, key, val`)

— C Function:**scm_hashv_set_x** (`table, key, val`)

— C Function:**scm_hashx_set_x** (`hash, assoc, table, key, val`)

— Scheme Procedure:

— Scheme Procedure:

— Scheme Procedure:

— C Function:

— C Function:

— C Function:

— C Function:

Associate

valwithkeyin the given hashtable. Ifkeyis already present then it's associated value is changed. If it's not present then a new entry is created.

— Scheme Procedure: **hash-remove!**` table key`

— Scheme Procedure:**hashq-remove!**` table key`

— Scheme Procedure:**hashv-remove!**` table key`

— Scheme Procedure:**hashx-remove!**` hash assoc table key`

— C Function:**scm_hash_remove_x** (`table, key`)

— C Function:**scm_hashq_remove_x** (`table, key`)

— C Function:**scm_hashv_remove_x** (`table, key`)

— C Function:**scm_hashx_remove_x** (`hash, assoc, table, key`)

— Scheme Procedure:

— Scheme Procedure:

— Scheme Procedure:

— C Function:

— C Function:

— C Function:

— C Function:

Remove any association for

keyin the given hashtable. Ifkeyis not intablethen nothing is done.

— Scheme Procedure: **hash**` key size`

— Scheme Procedure:**hashq**` key size`

— Scheme Procedure:**hashv**` key size`

— C Function:**scm_hash** (`key, size`)

— C Function:**scm_hashq** (`key, size`)

— C Function:**scm_hashv** (`key, size`)

— Scheme Procedure:

— Scheme Procedure:

— C Function:

— C Function:

— C Function:

Return a hash value for

key. This is a number in the range 0 tosize-1, which is suitable for use in a hash table of the givensize.Note that

`hashq`

and`hashv`

may use internal addresses of objects, so if an object is garbage collected and re-created it can have a different hash value, even when the two are notionally`eq?`

. For instance with symbols,(hashq 'something 123) ⇒ 19 (gc) (hashq 'something 123) ⇒ 62In normal use this is not a problem, since an object entered into a hash table won't be garbage collected until removed. It's only if hashing calculations are somehow separated from normal references that its lifetime needs to be considered.

— Scheme Procedure: **hash-get-handle**` table key`

— Scheme Procedure:**hashq-get-handle**` table key`

— Scheme Procedure:**hashv-get-handle**` table key`

— Scheme Procedure:**hashx-get-handle**` hash assoc table key`

— C Function:**scm_hash_get_handle** (`table, key`)

— C Function:**scm_hashq_get_handle** (`table, key`)

— C Function:**scm_hashv_get_handle** (`table, key`)

— C Function:**scm_hashx_get_handle** (`hash, assoc, table, key`)

— Scheme Procedure:

— Scheme Procedure:

— Scheme Procedure:

— C Function:

— C Function:

— C Function:

— C Function:

Return the

`(`

key`.`

value`)`

pair forkeyin the given hashtable, or`#f`

ifkeyis not intable.

— Scheme Procedure: **hash-create-handle!**` table key init`

— Scheme Procedure:**hashq-create-handle!**` table key init`

— Scheme Procedure:**hashv-create-handle!**` table key init`

— Scheme Procedure:**hashx-create-handle!**` hash assoc table key init`

— C Function:**scm_hash_create_handle_x** (`table, key, init`)

— C Function:**scm_hashq_create_handle_x** (`table, key, init`)

— C Function:**scm_hashv_create_handle_x** (`table, key, init`)

— C Function:**scm_hashx_create_handle_x** (`hash, assoc, table, key, init`)

— Scheme Procedure:

— Scheme Procedure:

— Scheme Procedure:

— C Function:

— C Function:

— C Function:

— C Function:

Return the

`(`

key`.`

value`)`

pair forkeyin the given hashtable. Ifkeyis not intablethen create an entry for it withinitas the value, and return that pair.

— Scheme Procedure: **hash-map->list**` proc table`

— Scheme Procedure:**hash-for-each**` proc table`

— C Function:**scm_hash_map_to_list** (`proc, table`)

— C Function:**scm_hash_for_each** (`proc, table`)

— Scheme Procedure:

— C Function:

— C Function:

Apply

procto the entries in the given hashtable. Each call is`(`

prockeyvalue`)`

.`hash-map->list`

returns a list of the results from these calls,`hash-for-each`

discards the results and returns an unspecified value.Calls are made over the table entries in an unspecified order, and for

`hash-map->list`

the order of the values in the returned list is unspecified. Results will be unpredictable iftableis modified while iterating.For example the following returns a new alist comprising all the entries from

`mytable`

, in no particular order.(hash-map->list cons mytable)

— Scheme Procedure: **hash-for-each-handle**` proc table`

— C Function:**scm_hash_for_each_handle** (`proc, table`)

— C Function:

Apply

procto the entries in the given hashtable. Each call is`(`

prochandle`)`

, wherehandleis a`(`

key`.`

value`)`

pair. Return an unspecified value.

`hash-for-each-handle`

differs from`hash-for-each`

only in the argument list ofproc.

— Scheme Procedure: **hash-fold**` proc init table`

— C Function:**scm_hash_fold** (`proc, init, table`)

— C Function:

Accumulate a result by applying

procto the elements of the given hashtable. Each call is`(`

prockeyvalueprior-result`)`

, wherekeyandvalueare from thetableandprior-resultis the return from the previousproccall. For the first call,prior-resultis the giveninitvalue.Calls are made over the table entries in an unspecified order. Results will be unpredictable if

tableis modified while`hash-fold`

is running.For example, the following returns a count of how many keys in

`mytable`

are strings.(hash-fold (lambda (key value prior) (if (string? key) (1+ prior) prior)) 0 mytable)