---

2.1.6 Hash tables

The hash-tables defined by Common Lisp have limited utility because they are limited to testing their keys using the equality predicates provided by (pre-CLOS) Common Lisp. CMUCL overcomes this limitation by allowing its users to specify new hash table tests and hashing methods. The hashing method must also be specified, since the compiler is unable to determine a good hashing function for an arbitrary equality (equivalence) predicate.

Function: extensions:define-hash-table-test hash-table-test-name test-function hash-function ¶

The hash-table-test-name must be a symbol. The test-function takes two objects and returns true iff they are the same. The hash-function takes one object and returns two values: the (positive fixnum) hash value and true if the hashing depends on pointer values and will have to be redone if the object moves.

To create a hash-table using this new “test” (really, a test/hash-function pair), use (make-hash-table :test hash-table-test-name ...).

Note that it is the hash-table-test-name that will be returned by the function hash-table-test, when applied to a hash-table created using this function.

This function updates hash-table-tests, which is now internal.

CMUCL also supports a number of weak hash tables. These weak tables are created using the :weak-p argument to make-hash-table. Normally, a reference to an object as either the key or value of the hash-table will prevent that object from being garbage-collected. However, in a weak table, if the only reference is the hash-table, the object can be collected.

The possible values for :weak-p are listed below. An entry in the table remains if the condition holds

:key

The key is referenced elsewhere

:value

The value is referenced elsewhere

:key-and-value

Both the key and value are referenced elsewhere

:key-or-value

Either the key or value are referenced elsewhere

T

For backward compatibility, this means the same as :key.

If the condition does not hold, the object can be removed from the hash table.

Weak hash tables can only be created if the test is eq or eql. An error is signaled if this is not the case.

Function: make-hash-table &key :test :size :rehash-size :rehash-threshold :weak-p ¶

Creates a hash-table with the specified properties.