X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/1107d4ca499749fbe800ecd58eba33b701b92317..99543e8b33e5914918a8caa9b1c5b5cf5400c57b:/lispref/hash.texi diff --git a/lispref/hash.texi b/lispref/hash.texi index e20b67b430..7b4c8c6771 100644 --- a/lispref/hash.texi +++ b/lispref/hash.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/hash @node Hash Tables, Symbols, Sequences Arrays Vectors, Top @@ -27,9 +27,9 @@ There is no way to share structure between two hash tables, 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) @@ -46,10 +46,10 @@ of object and are used only for recording interned symbols (@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 @@ -76,8 +76,10 @@ alternatives: @table @code @item eql -Keys which are numbers are ``the same'' if they are equal in value; -otherwise, two distinct objects are never ``the same''. +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''. @item eq Any two distinct Lisp objects are ``different'' as keys. @@ -95,20 +97,31 @@ 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, @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-and-value} or @code{t}, both the key and +the value must be live in order to preserve the association. Thus, +the hash table does not protect either keys or values from garbage +collection; if either one is collected as garbage, that removes the +association. + +If @var{weak} is @code{key-or-value}, either the key or +the value can preserve the association. Thus, associations are +removed from the hash table when both their key and value would be +collected as garbage (if not for references 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, -both are weak). +referenced in the hash table are preserved from garbage collection. @item :size @var{size} This specifies a hint for how many associations you plan to store in the @@ -133,11 +146,11 @@ number. 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 @@ -147,15 +160,16 @@ This is equivalent to @code{make-hash-table}, but with a different style argument list. The argument @var{test} specifies the method of key lookup. -If you want to specify other parameters, you should use -@code{make-hash-table}. +This function is obsolete. Use @code{make-hash-table} instead. @end defun @node Hash Access @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 @@ -165,7 +179,7 @@ association in @var{table}. @end defun @tindex puthash -@defun puthash key value table +@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. @@ -176,6 +190,10 @@ value @var{value}. If @var{key} already has an association in This function removes the association for @var{key} from @var{table}, if there is one. If @var{key} has no association, @code{remhash} does nothing. + +@b{Common Lisp note:} In Common Lisp, @code{remhash} returns +non-@code{nil} if it actually removed an association and @code{nil} +otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}. @end defun @tindex clrhash @@ -183,14 +201,18 @@ nothing. This function removes all the associations from hash table @var{table}, so that it becomes empty. This is also called @dfn{clearing} the hash table. + +@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty +@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 @@ -232,8 +254,24 @@ including negative integers. 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 -This example creates a hash table whose keys are strings that are +@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. + +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; 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 @@ -243,27 +281,21 @@ compared case-insensitively. (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 -@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 @@ -313,3 +345,7 @@ This returns the rehash threshold of @var{table}. @defun hash-table-size table This returns the current nominal size of @var{table}. @end defun + +@ignore + arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e +@end ignore