Basic Hash Table Operations (MIT/GNU Scheme 10.1.4)

Next: Resizing of Hash Tables, Previous: Construction of Hash Tables, Up: Hash Tables [Contents][Index]

#### 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-set! hash-table key datum
obsolete 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-ref hash-table key [get-default]

  Returns the datum associated with key in hash-table. If there is no association for key, and get-default is provided, it is called with no arguments and the value it yields is returned; if get-default is not provided, an error is signaled.

  The average time required by this operation is bounded by a constant.

procedure: hash-table-ref/default hash-table key default
obsolete procedure: hash-table/get hash-table key default

  Equivalent to

      (hash-table-ref hash-table key (lambda () default))

procedure: hash-table-delete! hash-table key
obsolete 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
obsolete 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-size hash-table
obsolete procedure: hash-table/count hash-table

  Returns the number of associations in hash-table as an exact non-negative integer. If hash-table does not hold its keys and data strongly, this is a conservative upper bound that may count some associations whose keys or data 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-keys hash-table
obsolete 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-values hash-table
obsolete 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-walk hash-table procedure
obsolete 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-delete!` to remove the association being processed.

The following procedure is useful when there is no sensible default value for `hash-table-ref` and the caller must choose between different actions depending on whether there is a datum associated with the key.

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.

procedure: hash-table-update! hash-table key procedure [get-default]

  Procedure must be a procedure of one argument and get-default, if supplied, must be a procedure of zero arguments. Applies procedure to the datum associated with key in hash-table or to the value of calling get-default if there is no association for key, associates the result with key, and returns an unspecified value. If get-default is not supplied and there’s no association for key, an error is signaled.

  The average time required by this operation is bounded by a constant.

procedure: hash-table-update!/default hash-table key procedure default
obsolete procedure: hash-table/modify! hash-table key default procedure

  Equivalent to

      (hash-table-update! hash-table key procedure (lambda () default))

procedure: hash-table-intern! hash-table key get-default
obsolete procedure: hash-table/intern! hash-table key get-default

  Get-default must be a procedure of zero arguments. Ensures that hash-table has an association for key and returns the associated datum. If hash-table did not have a datum associated with key, get-default is called and its value is used to create a new association for key.

  The average time required by this operation is bounded by a constant.

The following procedure is sometimes useful in conjunction with weak and ephemeral hash tables. Normally it is not needed, because such hash tables clean themselves automatically as they are used.

procedure: hash-table-clean! hash-table
obsolete procedure: hash-table/clean! hash-table

  If hash-table is a type of hash table that holds its keys or data weakly or ephemerally, this procedure recovers any space that was being used to record associations for objects that have been reclaimed by the garbage collector. Otherwise, this procedure does nothing. In either case, it returns an unspecified result.

Next: Resizing of Hash Tables, Previous: Construction of Hash Tables, Up: Hash Tables [Contents][Index]