@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1999, 2003 Free Software Foundation, Inc.
+@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005,
+@c 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/hash
@node Hash Tables, Symbols, Sequences Arrays Vectors, Top
@chapter Hash Tables
@cindex hash tables
+@cindex lookup tables
- A hash table is a very fast kind of lookup table, somewhat like
-an alist in that it maps keys to corresponding values. It differs
-from an alist in these ways:
+ A hash table is a very fast kind of lookup table, somewhat like an
+alist (@pxref{Association Lists}) in that it maps keys to
+corresponding values. It differs from an alist in these ways:
@itemize @bullet
@item
the way two alists can share a common tail.
@end itemize
- Emacs Lisp (starting with Emacs 21) provides a general-purpose hash
-table data type, along with a series of functions for operating on them.
-Hash tables have no read syntax, and print in hash notation, like this:
+ Emacs Lisp provides a general-purpose hash table data type, along
+with a series of functions for operating on them. Hash tables have no
+read syntax, and print in hash notation, like this:
@example
(make-hash-table)
(@pxref{Creating Symbols}).
@menu
-* Creating Hash::
-* Hash Access::
-* Defining Hash::
-* Other Hash::
+* Creating Hash:: Functions to create hash tables.
+* Hash Access:: Reading and writing the hash table contents.
+* Defining Hash:: Defining new comparison methods
+* Other Hash:: Miscellaneous.
@end menu
@node Creating Hash
@section Creating Hash Tables
+@cindex creating hash tables
The principal function for creating a hash table is
@code{make-hash-table}.
-@tindex make-hash-table
@defun 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
Keys which are numbers are ``the same'' if they are @code{equal}, that
is, if they are equal in value and either both are integers or both
are floating point numbers; otherwise, two distinct objects are never
-``the same''.
+``the same.''
@item eq
Any two distinct Lisp objects are ``different'' as keys.
@item equal
-Two Lisp objects are ``the same'', as keys, if they are equal
+Two Lisp objects are ``the same,'' as keys, if they are equal
according to @code{equal}.
@end table
The default value is 1.5.
@item :rehash-threshold @var{threshold}
-This specifies the criterion for when the hash table is ``full.'' The
-value, @var{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
-@var{threshold} is 0.8.
+This specifies the criterion for when the hash table is ``full'' (so
+it should be made larger). The value, @var{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 @var{threshold} is 0.8.
@end table
@end defun
-@tindex makehash
@defun makehash &optional test
This is equivalent to @code{make-hash-table}, but with a different style
argument list. The argument @var{test} specifies the method
@section Hash Table Access
This section describes the functions for accessing and storing
-associations in a hash table.
+associations in a hash table. In general, any Lisp object can be used
+as a hash key, unless the comparison method imposes limits. Any Lisp
+object can also be used as the value.
-@tindex gethash
@defun gethash key table &optional default
This function looks up @var{key} in @var{table}, and returns its
associated @var{value}---or @var{default}, if @var{key} has no
association in @var{table}.
@end defun
-@tindex puthash
@defun puthash key value table
This function enters an association for @var{key} in @var{table}, with
value @var{value}. If @var{key} already has an association in
@var{table}, @var{value} replaces the old associated value.
@end defun
-@tindex remhash
@defun remhash key table
This function removes the association for @var{key} from @var{table}, if
there is one. If @var{key} has no association, @code{remhash} does
otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}.
@end defun
-@tindex clrhash
@defun clrhash table
This function removes all the associations from hash table @var{table},
so that it becomes empty. This is also called @dfn{clearing} the hash
@var{table}. In Emacs Lisp, it returns @code{nil}.
@end defun
-@tindex maphash
@defun maphash function table
@anchor{Definition of maphash}
This function calls @var{function} once for each of the associations in
@var{table}. The function @var{function} should accept two
arguments---a @var{key} listed in @var{table}, and its associated
-@var{value}.
+@var{value}. @code{maphash} returns @code{nil}.
@end defun
@node Defining Hash
@section Defining Hash Comparisons
@cindex hash code
+@cindex define hash comparisons
You can define new methods of key lookup by means of
@code{define-hash-table-test}. In order to use this feature, you need
function to compute the hash code from a key, and a function to compare
two keys directly.
-@tindex define-hash-table-test
@defun define-hash-table-test name test-fn hash-fn
This function defines a new hash table test, named @var{name}.
@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}
@example
(defun case-fold-string= (a b)
(compare-strings a nil nil b nil nil t))
-
(defun case-fold-string-hash (a)
(sxhash (upcase a)))
-(define-hash-table-test 'case-fold 'case-fold-string=
- 'case-fold-string-hash))
+(define-hash-table-test 'case-fold
+ 'case-fold-string= 'case-fold-string-hash)
(make-hash-table :test 'case-fold)
@end example
Here are some other functions for working with hash tables.
-@tindex hash-table-p
@defun hash-table-p table
This returns non-@code{nil} if @var{table} is a hash table object.
@end defun
-@tindex copy-hash-table
@defun copy-hash-table table
This function creates and returns a copy of @var{table}. Only the table
itself is copied---the keys and values are shared.
@end defun
-@tindex hash-table-count
@defun hash-table-count table
This function returns the actual number of entries in @var{table}.
@end defun
-@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}).
@end defun
-@tindex hash-table-weakness
@defun hash-table-weakness table
This function returns the @var{weak} value that was specified for hash
table @var{table}.
@end defun
-@tindex hash-table-rehash-size
@defun hash-table-rehash-size table
This returns the rehash size of @var{table}.
@end defun
-@tindex hash-table-rehash-threshold
@defun hash-table-rehash-threshold table
This returns the rehash threshold of @var{table}.
@end defun
-@tindex hash-table-size
@defun hash-table-size table
This returns the current nominal size of @var{table}.
@end defun
HCoop / bpt / emacs.git / blobdiff