Re: expose XHASH [patch]

[Paul Pogonyshev <pogonyshev@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 1392 bytes --]

Second patch iteration, taking into account all comments by Paul Eggert.

Paul




* src/fns.c (Fsxhash_eq, Fsxhash_eql): New functions.

* doc/lispref/hash.texi (Defining Hash): Document 'sxhash-eq' and 'sxhash-eql'.

* etc/NEWS: Mention 'sxhash-eq' and 'sxhash-eql'.

On 1 April 2016 at 11:44, Paul Pogonyshev <pogonyshev@gmail.com> wrote:
> Paul Eggert wrote:
>> The documentation for the new function should be next to the documentation for sxhash.
>
> I just skipped all the examples related to 'sxhash'. But I don't mind.
>
>> Shouldn't we expose hashfn_eq, not XHASH? After all, (make-hash-table :test 'eq ...) uses hashfn_eq, not XHASH.
>
> Probably you are right. I don't know the internal details well enough
> to comment on this.
>
>> Should we also expose hashfn_eql, which is what make-hash-table uses by default? Or is that a waste of time since hashfn_eql is the default?
>
> I'd say expose it too, at least for the cases of composite hashing as
> in my example.
>
>> Not sure I like the name xhash. Maybe sxhash-eq instead? That would let us use the name sxhash-eql for hashfn_eql.
>
> I tried to keep familiar names (at least for those who work on C
> code), but if we change that to 'hashfn_eq' and additionally expose
> something for 'eql', I guess your idea is better.
>
> I'll wait if more comments on these points appear before creating next
> patch iteration.
>
> Paul

[-- Attachment #2: sxhash-eq[l].diff --]
[-- Type: text/plain, Size: 3827 bytes --]

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 8389c21..a197399 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -273,13 +273,34 @@ 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 @var{obj1})} and @code{(sxhash @var{obj2})} are the same
+integer.
+
+If the two objects are not @code{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
+
+@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
diff --git a/etc/NEWS b/etc/NEWS
index 726b4b9..2d91166 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -208,6 +208,12 @@ permanent and documented, and may be used by Lisp programs.  Its value
 is a list of currently open parenthesis positions, starting with the
 outermost parenthesis.
 
++++
+** New functions 'sxhash-eq' and 'sxhash-eql' return hash codes of a
+Lisp object suitable for use with 'eq' and 'eql' correspondingly.  If
+two objects are 'eq' ('eql'), then the result of 'sxhash-eq'
+('sxhash-eql') on them will be the same.
+
 \f
 * Changes in Emacs 25.2 on Non-Free Operating Systems
 
diff --git a/src/fns.c b/src/fns.c
index 114a556..825e443 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -4457,6 +4457,25 @@ DEFUN ("sxhash", Fsxhash, Ssxhash, 1, 1, 0,
   return make_number (hash);
 }
 
+DEFUN ("sxhash-eq", Fsxhash_eq, Ssxhash_eq, 1, 1, 0,
+       doc: /* Compute identity hash code for OBJ and return it as integer.
+In other words, hash codes of two non-`eq' lists will be (most likely)
+different, even if the lists contain the same elements. */)
+  (Lisp_Object obj)
+{
+  return make_number (hashfn_eq (NULL, obj));
+}
+
+DEFUN ("sxhash-eql", Fsxhash_eql, Ssxhash_eql, 1, 1, 0,
+       doc: /* Compute identity hash code for OBJ and return it as integer.
+In comparison to `sxhash-eq', it is also guaranteed that hash codes
+of equal float numbers will be the same, even if the numbers are not
+the same Lisp object. */)
+  (Lisp_Object obj)
+{
+  return make_number (hashfn_eql (NULL, obj));
+}
+
 
 DEFUN ("make-hash-table", Fmake_hash_table, Smake_hash_table, 0, MANY, 0,
        doc: /* Create and return a new hash table.
@@ -5068,6 +5087,8 @@ syms_of_fns (void)
   DEFSYM (Qkey_and_value, "key-and-value");
 
   defsubr (&Ssxhash);
+  defsubr (&Ssxhash_eq);
+  defsubr (&Ssxhash_eql);
   defsubr (&Smake_hash_table);
   defsubr (&Scopy_hash_table);
   defsubr (&Shash_table_count);