@itemize @bullet
@item
-Lookup in a hash table is extremely fast---in fact, the time required
-is essentially @emph{independent} of how many elements are stored
-in the table.
+Lookup in a hash table is extremely fast for large tables---in fact, the
+time required is essentially @emph{independent} of how many elements are
+stored in the table. For smaller tables (a few tens of elements)
+alists may still be faster because hash tables have a more-or-less
+constant overhead.
@item
The correspondences in a hash table are in no particular order.
@result{} #<hash-table 'eql nil 0/65 0x83af980>
@end example
+@noindent
+(The term ``hash notation'' refers to the initial @samp{#}
+character---@pxref{Printed Representation}---and has nothing to do with
+the term ``hash table.'')
+
Obarrays are also a kind of hash table, but they are a different type
of object and are used only for recording interned symbols
(@pxref{Creating Symbols}).
them.
Several keywords make sense in @code{make-hash-table}, but the only two
-that you really need to know about are @code{:test} and @code{:weak}.
+that you really need to know about are @code{:test} and @code{:weakness}.
@table @code
@item :test @var{test}
value in the hash table preserves it from garbage collection.
The value, @var{weak}, must be one of @code{nil}, @code{key},
-@code{value} or @code{t}. If @var{weak} is @code{key} or @code{t}, 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.
-
-Likewise, if @var{weak} is @code{value} or @code{t}, 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
+@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
+which is an alias for @code{key-and-value}. If @var{weak} is @code{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 @var{weak} is @code{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 @var{weak} is @code{key-or-value}, associations are removed from the
+hash table when either their key or their value part would be collected
+as garbage, not counting references to the key and value from weak hash
+tables. Likewise, if @var{weak} is @code{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 @var{weak} is @code{nil}, so that all keys and values
referenced in the hash table are preserved from garbage collection. If
@var{weak} is @code{t}, neither keys nor values are protected (that is,
@item :size @var{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 to
+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,
+doing that takes some extra time.
The default size is 65.
This function returns the actual number of entries in @var{table}.
@end defun
-@tindex hash-table-rehash-test
-@defun hash-table-rehash-test table
+@tindex hash-table-test
+@defun hash-table-test table
This returns the @var{test} value that was given when @var{table} was
created, to specify how to hash and compare keys. See
@code{make-hash-table} (@pxref{Creating Hash}).
This returns the rehash threshold of @var{table}.
@end defun
-@tindex hash-table-rehash-size
-@defun hash-table-rehash-size table
+@tindex hash-table-size
+@defun hash-table-size table
This returns the current nominal size of @var{table}.
@end defun