procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve sxhash-equal documentation

Browse source 
* 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.
This commit is contained in:
Lars Ingebrigtsen 2022-06-28 14:58:20 +02:00
parent 98c9105f05
commit c23a49d256
2 changed files with 11 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
doc/lispref/hash.texi
View file

@ -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

6
src/fns.c
View file

@ -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)