From c23a49d256771739d78eca1f371f69c46979d90c Mon Sep 17 00:00:00 2001 From: Lars Ingebrigtsen Date: Tue, 28 Jun 2022 14:58:20 +0200 Subject: [PATCH] Improve sxhash-equal documentation * doc/lispref/hash.texi (Defining Hash): Explain more about what sxhash-equal is for and what the caveats are. * src/fns.c (Fsxhash_eql, Fsxhash_equal): Clarify doc string. --- doc/lispref/hash.texi | 10 +++++++--- src/fns.c | 6 ++++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index a566d898240..62649455214 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -289,9 +289,13 @@ If two objects @var{obj1} and @var{obj2} are @code{equal}, then 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}. +@code{sxhash-equal} are usually different, but not always. +@code{sxhash-equal} is designed to be reasonably fast (since it's used +for indexing hash tables) so it won't recurse deeply into nested +structures. In addition; once in a rare while, by luck, you will +encounter two distinct-looking simple objects that give the same +result from @code{sxhash-equal}. So you can't, in general, use +@code{sxhash-equal} to check whether an object has changed. @b{Common Lisp note:} In Common Lisp a similar function is called @code{sxhash}. Emacs provides this name as a compatibility alias for diff --git a/src/fns.c b/src/fns.c index 6be6b6d6167..7553a094468 100644 --- a/src/fns.c +++ b/src/fns.c @@ -4923,7 +4923,8 @@ 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'. -If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)). +If (eql A B), then (= (sxhash-eql A) (sxhash-eql B)), but the opposite +isn't necessarily true. Hash codes are not guaranteed to be preserved across Emacs sessions. */) (Lisp_Object obj) @@ -4933,7 +4934,8 @@ 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'. -If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)). +If (equal A B), then (= (sxhash-equal A) (sxhash-equal B)), but the +opposite isn't necessarily true. Hash codes are not guaranteed to be preserved across Emacs sessions. */) (Lisp_Object obj) -- 2.39.5