Basic Hash Table Operations - MIT/GNU Scheme 7.7.90+
Description: MIT/GNU Scheme 7.7.90+

Next: Resizing of Hash Tables, Previous: Construction of Hash Tables, Up: Hash Tables

#### 11.4.2 Basic Hash Table Operations

The procedures described in this section are the basic operations on hash tables. They provide the functionality most often needed by programmers. Subsequent sections describe other operations that provide additional functionality needed by some applications.

— procedure: hash-table? object

> Returns `#t` if object is a hash table, otherwise returns `#f`.

— procedure: hash-table/put! hash-table key datum

> Associates datum with key in hash-table and returns an unspecified result. The average time required by this operation is bounded by a constant.

— procedure: hash-table/get hash-table key default

> Returns the datum associated with key in hash-table. If there is no association for key, default is returned. The average time required by this operation is bounded by a constant.

— procedure: hash-table/remove! hash-table key

> If hash-table has an association for key, removes it. Returns an unspecified result. The average time required by this operation is bounded by a constant.

— procedure: hash-table/clear! hash-table

> Removes all associations in hash-table and returns an unspecified result. The average and worst-case times required by this operation are bounded by a constant.

— procedure: hash-table/count hash-table

> Returns the number of associations in hash-table as an exact non-negative integer. If hash-table holds its keys weakly, this is a conservative upper bound that may count some associations whose keys have recently been reclaimed by the garbage collector. The average and worst-case times required by this operation are bounded by a constant.

— procedure: hash-table->alist hash-table

> Returns the contents of hash-table as a newly allocated alist. Each element of the alist is a pair `(`key`.` datum`)` where key is one of the keys of hash-table, and datum is its associated datum. The average and worst-case times required by this operation are linear in the number of associations in the table.

— procedure: hash-table/key-list hash-table

> Returns a newly allocated list of the keys in hash-table. The average and worst-case times required by this operation are linear in the number of associations in the table.

— procedure: hash-table/datum-list hash-table

> Returns a newly allocated list of the datums in hash-table. Each element of the list corresponds to one of the associations in hash-table; if the table contains multiple associations with the same datum, so will this list. The average and worst-case times required by this operation are linear in the number of associations in the table.

— procedure: hash-table/for-each hash-table procedure

> Procedure must be a procedure of two arguments. Invokes procedure once for each association in hash-table, passing the association's key and datum as arguments, in that order. Returns an unspecified result. Procedure must not modify hash-table, with one exception: it is permitted to call `hash-table/remove!` to remove the association being processed.

The following procedure is an alternate form of `hash-table/get` that is useful in some situations. Usually, `hash-table/get` is preferable because it is faster.

— procedure: hash-table/lookup hash-table key if-found if-not-found

> If-found must be a procedure of one argument, and if-not-found must be a procedure of no arguments. If hash-table contains an association for key, if-found is invoked on the datum of the association. Otherwise, if-not-found is invoked with no arguments. In either case, the result yielded by the invoked procedure is returned as the result of `hash-table/lookup` (`hash-table/lookup` reduces into the invoked procedure, i.e. calls it tail-recursively). The average time required by this operation is bounded by a constant.