7.1 Creating Hash Tables

The principal function for creating a hash table is make-hash-table.

Function: make-hash-table &rest keyword-args

This function creates a new hash table according to the specified arguments. The arguments should consist of alternating keywords (particular symbols recognized specially) and values corresponding to them.

Several keywords make sense in make-hash-table, but the only two that you really need to know about are :test and :weakness.

:test test

This specifies the method of key lookup for this hash table. The default is eql; eq and equal are other alternatives:

eql

Keys which are numbers are "the same" if they are equal in value; otherwise, two distinct objects are never "the same".

eq

Any two distinct Lisp objects are "different" as keys.

equal

Two Lisp objects are "the same", as keys, if they are equal according to equal.

You can use define-hash-table-test (see section 7.3 Defining Hash Comparisons) to define additional possibilities for test.

:weakness weak

The weakness of a hash table specifies whether the presence of a key or value in the hash table preserves it from garbage collection.

The value, weak, must be one of nil, key, value, key-or-value, key-and-value, or t which is an alias for key-and-value. If weak is key then the hash table does not prevent its keys from being collected as garbage (if they are not referenced anywhere else); if a particular key does get collected, the corresponding association is removed from the hash table.

If weak is value, then the hash table does not prevent values from being collected as garbage (if they are not referenced anywhere else); if a particular value does get collected, the corresponding association is removed from the hash table.

If weak is key-or-value or t, the hash table does not protect either keys or values from garbage collection; if either one is collected as garbage, the association is removed.

If weak is key-and-value, associations are removed from the hash table when both their key and value would be collected as garbage, again not considering references to the key and value from weak hash tables.

The default for weak is nil, so that all keys and values referenced in the hash table are preserved from garbage collection. If weak is t, neither keys nor values are protected (that is, both are weak).

:size size

This specifies a hint for how many associations you plan to store in the hash table. If you know the approximate number, you can make things a little more efficient by specifying it this way. If you specify too small a size, the hash table will grow automatically when necessary, but doing that takes some extra time.

The default size is 65.

:rehash-size rehash-size

When you add an association to a hash table and the table is "full," it grows automatically. This value specifies how to make the hash table larger, at that time.

If rehash-size is an integer, it should be positive, and the hash table grows by adding that much to the nominal size. If rehash-size is a floating point number, it had better be greater than 1, and the hash table grows by multiplying the old size by that number.

The default value is 1.5.

:rehash-threshold threshold

This specifies the criterion for when the hash table is "full." The value, threshold, should be a positive floating point number, no greater than 1. The hash table is "full" whenever the actual number of entries exceeds this fraction of the nominal size. The default for threshold is 0.8.

Function: makehash &optional test

This is equivalent to make-hash-table, but with a different style argument list. The argument test specifies the method of key lookup.

If you want to specify other parameters, you should use make-hash-table.