*** empty log message ***

[gnu-emacs] / lispref / hash.texi

diff --git a/lispref/hash.texi b/lispref/hash.texi
index c6bb9caac003ef0fe8847c30723900cabf79e3af..86a36a57a6e960921440eafaaeb12004652f20ff 100644 (file)
--- a/lispref/hash.texi
+++ b/lispref/hash.texi
@@ -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
 
 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)
 
 @example
 (make-hash-table)


@@ -46,10 +46,10 @@ of object and are used only for recording interned symbols
 (@pxref{Creating Symbols}).
 
 @menu
 (@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
 @end menu
 
 @node Creating Hash


@@ -76,8 +76,10 @@ alternatives:
 
 @table @code
 @item eql
 
 @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.
 
 @item eq
 Any two distinct Lisp objects are ``different'' as keys.


@@ -96,7 +98,7 @@ value in the hash table preserves it from garbage collection.
 
 The value, @var{weak}, must be one of @code{nil}, @code{key},
 @code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
 
 The value, @var{weak}, must be one of @code{nil}, @code{key},
 @code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}

-which is an alias for @code{key-or-value}.  If @var{weak} is @code{key}
+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
 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


@@ -107,19 +109,19 @@ 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.
 
 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} 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-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.
+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
 
 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
 
 @item :size @var{size}
 This specifies a hint for how many associations you plan to store in the


@@ -144,11 +146,11 @@ number.
 The default value is 1.5.
 
 @item :rehash-threshold @var{threshold}
 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
 
 @end table
 @end defun
 


@@ -158,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.
 
 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
 @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
 
 @tindex gethash
 @defun gethash key table &optional default


@@ -187,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.
 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
 @end defun
 
 @tindex clrhash


@@ -194,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.
 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
 @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
 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
 @end defun
 
 @node Defining Hash


@@ -255,8 +266,8 @@ 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}
 @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
+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
 
 result from @code{sxhash}.
 @end defun
 


@@ -270,8 +281,8 @@ compared case-insensitively.
 (defun case-fold-string-hash (a)
   (sxhash (upcase a)))
 
 (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
 
 (make-hash-table :test 'case-fold)
 @end example