@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.
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} or @code{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 @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,
The specified functions are stored in the property list of @var{name}
under the property @code{hash-table-test}; the property value's form is
@code{(@var{test-fn} @var{hash-fn})}.
+@end defun
+
+@tindex sxhash
+@defun sxhash obj
+This function returns a hash code for Lisp object @var{obj}.
+This is an integer which reflects the contents of @var{obj}
+and the other Lisp objects it points to.
-This example creates a hash table whose keys are strings that are
+If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
+@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+
+If the two objects are not equal, the values returned by @code{sxhash}
+are usually different, but not always; but once in a rare while, by
+luck, you will encounter two distinct-looking objects that give the same
+result from @code{sxhash}.
+@end defun
+
+ This example creates a hash table whose keys are strings that are
compared case-insensitively.
@example
(make-hash-table :test 'case-fold)
@end example
-@end defun
-@tindex sxhash
-@defun sxhash obj
-This function returns a hash code for Lisp object @var{obj}.
-This is an integer which reflects the contents of @var{obj}
-and the other Lisp objects it points to.
+ Here is how you could define a hash table test equivalent to the
+predefined test value @code{equal}. The keys can be any Lisp object,
+and equal-looking objects are considered the same key.
-If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
-@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+@example
+(define-hash-table-test 'contents-hash 'equal 'sxhash)
-If the two objects are not equal, the values returned by @code{sxhash}
-are usually different, but not always; but once in a rare while, by
-luck, you will encounter two distinct-looking objects that give the same
-result from @code{sxhash}.
-@end defun
+(make-hash-table :test 'contents-hash)
+@end example
@node Other Hash
@section Other Hash Table Functions