emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] master cf28594 2/4: Improve doc for hash tables


From: Paul Eggert
Subject: [Emacs-diffs] master cf28594 2/4: Improve doc for hash tables
Date: Sun, 21 Jul 2019 14:24:20 -0400 (EDT)

branch: master
commit cf285946bee56912286f75e4d1215214bc7c5b4b
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    Improve doc for hash tables
    
    * doc/lispref/hash.texi (Creating Hash, Defining Hash):
    * src/fns.c (Fsxhash_eq, Fsxhash_eql, Fsxhash_equal):
    Say that hashes are fixnums.
    (Fmake_hash_table): Say that that an integer rehash-size
    should be a fixnum.
    * doc/lispref/hash.texi (Defining Hash): Say that hash and
    comparison functions should be consistent and pure, and should
    return quickly.
---
 doc/lispref/hash.texi | 27 ++++++++++++++++-----------
 src/fns.c             |  8 ++++----
 2 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 9b900e6..0515314 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -132,7 +132,7 @@ 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
+If @var{rehash-size} is a fixnum, it should be positive and the hash
 table grows by adding approximately that much to the nominal size.  If
 @var{rehash-size} is floating point, it had better be greater
 than 1, and the hash table grows by multiplying the old size by
@@ -239,14 +239,19 @@ to understand how hash tables work, and what a @dfn{hash 
code} means.
 
   You can think of a hash table conceptually as a large array of many
 slots, each capable of holding one association.  To look up a key,
-@code{gethash} first computes an integer, the hash code, from the key.
-It reduces this integer modulo the length of the array, to produce an
+@code{gethash} first computes a fixnum, the hash code, from the key.
+It reduces this fixnum modulo the length of the array, to produce an
 index in the array.  Then it looks in that slot, and if necessary in
 other nearby slots, to see if it has found the key being sought.
 
   Thus, to define a new method of key lookup, you need to specify both a
 function to compute the hash code from a key, and a function to compare
-two keys directly.
+two keys directly.  The two functions should be consistent with each
+other: that is, two keys' hash codes should be the same if the keys
+compare as equal.  Also, since the two functions can be called at any
+time (such as by the garbage collector), the functions should be free
+of side effects and should return quickly, and their behavior should
+depend on only on properties of the keys that do not change.
 
 @defun define-hash-table-test name test-fn hash-fn
 This function defines a new hash table test, named @var{name}.
@@ -260,9 +265,9 @@ The function @var{test-fn} should accept two arguments, two 
keys, and
 return non-@code{nil} if they are considered the same.
 
 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 integers for hash codes,
-including negative integers.
+a fixnum that is the hash code of that key.  For good results, the
+function should use the whole range of fixnums for hash codes,
+including negative fixnums.
 
 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
@@ -271,12 +276,12 @@ under the property @code{hash-table-test}; the property 
value's form is
 
 @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}
+This is a fixnum that reflects the contents of @var{obj}
 and the other Lisp objects it points to.
 
 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.
+are the same fixnum.
 
 If the two objects are not @code{equal}, the values returned by
 @code{sxhash-equal} are usually different, but not always; once in a
@@ -294,7 +299,7 @@ result reflects identity of @var{obj}, but not its contents.
 
 If two objects @var{obj1} and @var{obj2} are @code{eq}, then
 @code{(sxhash-eq @var{obj1})} and @code{(sxhash-eq @var{obj2})} are
-the same integer.
+the same fixnum.
 @end defun
 
 @defun sxhash-eql obj
@@ -305,7 +310,7 @@ in which case a hash code is generated for the value.
 
 If two objects @var{obj1} and @var{obj2} are @code{eql}, then
 @code{(sxhash-eql @var{obj1})} and @code{(sxhash-eql @var{obj2})} are
-the same integer.
+the same fixnum.
 @end defun
 
   This example creates a hash table whose keys are strings that are
diff --git a/src/fns.c b/src/fns.c
index d7e1231..819eaec 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -4700,7 +4700,7 @@ sxhash (Lisp_Object obj, int depth)
  ***********************************************************************/
 
 DEFUN ("sxhash-eq", Fsxhash_eq, Ssxhash_eq, 1, 1, 0,
-       doc: /* Return an integer hash code for OBJ suitable for `eq'.
+       doc: /* Return a fixnum hash code for OBJ suitable for `eq'.
 If (eq A B), then (= (sxhash-eq A) (sxhash-eq B)).
 
 Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
@@ -4710,7 +4710,7 @@ Hash codes are not guaranteed to be preserved across 
Emacs sessions.  */)
 }
 
 DEFUN ("sxhash-eql", Fsxhash_eql, Ssxhash_eql, 1, 1, 0,
-       doc: /* Return an integer hash code for OBJ suitable for `eql'.
+       doc: /* Return a fixnum hash code for OBJ suitable for `eql'.
 If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)).
 
 Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
@@ -4720,7 +4720,7 @@ Hash codes are not guaranteed to be preserved across 
Emacs sessions.  */)
 }
 
 DEFUN ("sxhash-equal", Fsxhash_equal, Ssxhash_equal, 1, 1, 0,
-       doc: /* Return an integer hash code for OBJ suitable for `equal'.
+       doc: /* Return a fixnum hash code for OBJ suitable for `equal'.
 If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)).
 
 Hash codes are not guaranteed to be preserved across Emacs sessions.  */)
@@ -4744,7 +4744,7 @@ keys.  Default is `eql'.  Predefined are the tests `eq', 
`eql', and
 Default is 65.
 
 :rehash-size REHASH-SIZE - Indicates how to expand the table when it
-fills up.  If REHASH-SIZE is an integer, increase the size by that
+fills up.  If REHASH-SIZE is a fixnum, increase the size by that
 amount.  If it is a float, it must be > 1.0, and the new size is the
 old size multiplied by that factor.  Default is 1.5.
 



reply via email to

[Prev in Thread] Current Thread [Next in Thread]