7.6 Hash table extensions

7.6.2 Reference pages

hash-table-rehash-size Function

hash-table-rehash-threshold Function

hash-table-size Function

hash-table-test Function

Syntax:hash-table-rehash-size hash-table

Syntax:hash-table-rehash-threshold hash-table

Syntax:hash-table-size hash-table

Syntax:hash-table-test hash-table

These functions access components of a hash table created by the Common Lisp functionmake-hash-table:

hash-table-rehash-size accesses the:rehash-size component.
hash-table-rehash-threshold accesses the:rehash-threshold component.
hash-table-size accesses the:size component.
hash-table-test accesses the:test component.

You can use the Common Lisp macrosetf with the functionshash-table-rehash-size,hash-table-rehash-threshold, andhash-table-test to update the corresponding hash table component; you cannot update the:size component in this way.

See Also: rehash;make-hash-table (in CLtL2)

rehash Function

Syntax:rehash hash-table&optional new-option

The functionrehash either changes the size of the specified hash table or redistributes the keys as evenly as possible over the range of index values. This redistribution of keys, or rehashing, can improve the performance of hashing functions by reducing the number of probes that are necessary to find an element in the table.

The optional new-option argument has the following effects:

If the argument is not specified or if its value isnil, the hash table is rehashed, but its size is not changed.
If the value of the argument ist, the hash table size is increased by the amount specified by the hash table's:rehash-size keyword option.
If the argument is a fixnum, the new hash table size is set to that number. The actual table size is upgraded to the smallest prime not less than the value specified by the hash table's:size keyword option.
The:size parameter specifies a lower bound on the size of the hash table that is no larger than one-half the size of the Common Lisp constantarray-total-size-limit, though this bound is unrealistically high.
If the argument is a hash table, the hash-table argument is destructively copied into it, thereby replacing all of the former contents.

When the number of items being entered into a hash table exceeds the table's rehash threshold,rehash is called internally with new-option set tot to increase the size of the table.

Note: Hash tables of typeeq oreql might need to be rehashed after any relocating garbage collection, including any ephemeral scavengings. Rehashing is advised because the addresses of the keys entered in the table can change after a relocation. This kind of rehashing is not necessary for any table whose keys are all either symbols, fixnums, or characters.