; Merge from origin/emacs-25

[gnu-emacs] / doc / lispref / hash.texi

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index bb7a60e2e2df9c0f09d5d07e2a34074c4864ece5..4607bb0a0d13c394783873e1c3bece09decfbb1d 100644 (file)
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -1,6 +1,6 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1999, 2001-2016 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @node Hash Tables
 @chapter Hash Tables
 @c See the file elisp.texi for copying conditions.
 @node Hash Tables
 @chapter Hash Tables


@@ -31,10 +31,10 @@ the way two alists can share a common tail.
 with a series of functions for operating on them.  Hash tables have a
 special printed representation, which consists of @samp{#s} followed
 by a list specifying the hash table properties and contents.
 with a series of functions for operating on them.  Hash tables have a
 special printed representation, which consists of @samp{#s} followed
 by a list specifying the hash table properties and contents.

-@xref{Creating Hash}.  (Note that the term ``hash notation'', which
-refers to the initial @samp{#} character used in the printed
+@xref{Creating Hash}.
+(Hash notation, the initial @samp{#} character used in the printed

 representations of objects with no read representation, has nothing to
 representations of objects with no read representation, has nothing to

-do with the term ``hash table''.  @xref{Printed Representation}.)
+do with hash tables.  @xref{Printed Representation}.)

 
   Obarrays are also a kind of hash table, but they are a different type
 of object and are used only for recording interned symbols
 
   Obarrays are also a kind of hash table, but they are a different type
 of object and are used only for recording interned symbols


@@ -71,16 +71,16 @@ alternatives:
 
 @table @code
 @item eql
 
 @table @code
 @item eql

-Keys which are numbers are ``the same'' if they are @code{equal}, that
+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
 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''.
+are floating point; otherwise, two distinct objects are never
+the same.

 
 @item eq
 
 @item eq

-Any two distinct Lisp objects are ``different'' as keys.
+Any two distinct Lisp objects are different as keys.

 
 @item equal
 
 @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
 
 according to @code{equal}.
 @end table
 


@@ -128,35 +128,27 @@ doing that takes some extra time.
 The default size is 65.
 
 @item :rehash-size @var{rehash-size}
 The default size is 65.
 
 @item :rehash-size @var{rehash-size}

-When you add an association to a hash table and the table is ``full'',
+When you add an association to a hash table and the table is full,

 it grows automatically.  This value specifies how to make the hash table
 larger, at that time.
 
 If @var{rehash-size} is an integer, it should be positive, and the hash
 table grows by adding that much to the nominal size.  If
 it grows automatically.  This value specifies how to make the hash table
 larger, at that time.
 
 If @var{rehash-size} is an integer, it should be positive, and the hash
 table grows by adding that much to the nominal size.  If

-@var{rehash-size} is a floating point number, it had better be greater
+@var{rehash-size} is floating point, it had better be greater

 than 1, and the hash table grows by multiplying the old size by that
 number.
 
 The default value is 1.5.
 
 @item :rehash-threshold @var{threshold}
 than 1, and the hash table grows by multiplying the old size by that
 number.
 
 The default value is 1.5.
 
 @item :rehash-threshold @var{threshold}

-This specifies the criterion for when the hash table is ``full'' (so
+This specifies the criterion for when the hash table is full (so

 it should be made larger).  The value, @var{threshold}, should be a
 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
+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
 
 of the nominal size.  The default for @var{threshold} is 0.8.
 @end table
 @end defun
 

-@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
-of key lookup.
-
-This function is obsolete. Use @code{make-hash-table} instead.
-@end defun
-

 You can also create a new hash table using the printed representation
 for hash tables.  The Lisp reader can read this printed
 representation, provided each element in the specified hash table has
 You can also create a new hash table using the printed representation
 for hash tables.  The Lisp reader can read this printed
 representation, provided each element in the specified hash table has


@@ -188,6 +180,8 @@ Such objects may be added to the hash table after it is created.
 
 @node Hash Access
 @section Hash Table Access
 
 @node Hash Access
 @section Hash Table Access

+@cindex accessing hash tables
+@cindex hash table access

 
   This section describes the functions for accessing and storing
 associations in a hash table.  In general, any Lisp object can be used
 
   This section describes the functions for accessing and storing
 associations in a hash table.  In general, any Lisp object can be used


@@ -259,14 +253,14 @@ This function defines a new hash table test, named @var{name}.
 After defining @var{name} in this way, you can use it as the @var{test}
 argument in @code{make-hash-table}.  When you do that, the hash table
 will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
 After defining @var{name} in this way, you can use it as the @var{test}
 argument in @code{make-hash-table}.  When you do that, the hash table
 will use @var{test-fn} to compare key values, and @var{hash-fn} to compute

-a ``hash code'' from a key value.
+a hash code from a key value.

 
 The function @var{test-fn} should accept two arguments, two keys, and
 
 The function @var{test-fn} should accept two arguments, two keys, and

-return non-@code{nil} if they are considered ``the same''.
+return non-@code{nil} if they are considered the same.

 
 The function @var{hash-fn} should accept one argument, a key, and return
 
 The function @var{hash-fn} should accept one argument, a key, and return

-an integer that is the ``hash code'' of that key.  For good results, the
-function should use the whole range of integer values for hash codes,
+an integer that is the hash code of that key.  For good results, the
+function should use the whole range of integers for hash codes,

 including negative integers.
 
 The specified functions are stored in the property list of @var{name}
 including negative integers.
 
 The specified functions are stored in the property list of @var{name}


@@ -274,18 +268,43 @@ under the property @code{hash-table-test}; the property value's form is
 @code{(@var{test-fn} @var{hash-fn})}.
 @end defun
 
 @code{(@var{test-fn} @var{hash-fn})}.
 @end defun
 

-@defun sxhash obj
+@defun sxhash-equal 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 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 two objects @var{obj1} and @var{obj2} are @code{equal}, then
+@code{(sxhash-equal @var{obj1})} and @code{(sxhash-equal @var{obj2})}
+are the same integer.
+
+If the two objects are not @code{equal}, the values returned by
+@code{sxhash-equal} 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-equal}.
+
+@b{Common Lisp note:} In Common Lisp a similar function is called
+@code{sxhash}.  Emacs provides this name as a compatibility alias for
+@code{sxhash-equal}.
+@end defun
+
+@defun sxhash-eq obj
+This function returns a hash code for Lisp object @var{obj}.  Its
+result reflects identity of @var{obj}, but not its contents.
+
+If two objects @var{obj1} and @var{obj2} are @code{eq}, then
+@code{(xhash @var{obj1})} and @code{(xhash @var{obj2})} are the same
+integer.
+@end defun
+
+@defun sxhash-eql obj
+This function returns a hash code for Lisp object @var{obj} suitable
+for @code{eql} comparison.  I.e. it reflects identity of @var{obj}
+except for the case where the object is a float number, in which case
+hash code is generated for the value.

 
 

-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}.
+If two objects @var{obj1} and @var{obj2} are @code{eql}, then
+@code{(xhash @var{obj1})} and @code{(xhash @var{obj2})} are the same
+integer.

 @end defun
 
   This example creates a hash table whose keys are strings that are
 @end defun
 
   This example creates a hash table whose keys are strings that are


@@ -293,9 +312,9 @@ compared case-insensitively.
 
 @example
 (defun case-fold-string= (a b)
 
 @example
 (defun case-fold-string= (a b)

-  (compare-strings a nil nil b nil nil t))
+  (eq t (compare-strings a nil nil b nil nil t)))

 (defun case-fold-string-hash (a)
 (defun case-fold-string-hash (a)

-  (sxhash (upcase a)))
+  (sxhash-equal (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)


@@ -308,7 +327,7 @@ predefined test value @code{equal}.  The keys can be any Lisp object,
 and equal-looking objects are considered the same key.
 
 @example
 and equal-looking objects are considered the same key.
 
 @example

-(define-hash-table-test 'contents-hash 'equal 'sxhash)
+(define-hash-table-test 'contents-hash 'equal 'sxhash-equal)

 
 (make-hash-table :test 'contents-hash)
 @end example
 
 (make-hash-table :test 'contents-hash)
 @end example