From: Mattias Engdegård <mattiase@acm.org>
Date: Fri, 19 Jan 2024 14:52:13 +0000 (+0100)
Subject: Clarify permitted mutation in `maphash` documentation
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4eb81217cdf23e3f228ef3d95e7b5a0ceb95007c;p=emacs.git

Clarify permitted mutation in `maphash` documentation

* doc/lispref/hash.texi (Hash Access):
* src/fns.c (Fmaphash):
Make it clear what the function passed as argument can do.  Until now
these rules were unwritten, and are still unenforced.

(cherry picked from commit 7a87ca09a73d61b46bfcaca317095ce7545bd3f3)
---

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 3d3fe3e3be2..4270de664f1 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -206,6 +206,10 @@ This function calls @var{function} once for each of the associations in
 @var{table}.  The function @var{function} should accept two
 arguments---a @var{key} listed in @var{table}, and its associated
 @var{value}.  @code{maphash} returns @code{nil}.
+
+@var{function} is allowed to call @code{puthash} to set a new value
+for @var{key} and @code{remhash} to remove @var{key}, but should not
+add, remove or modify other associations in @var{table}.
 @end defun
 
 @node Defining Hash
diff --git a/src/fns.c b/src/fns.c
index 4531b237824..f862c1470c4 100644
--- a/src/fns.c
+++ b/src/fns.c
@@ -5651,6 +5651,8 @@ DEFUN ("remhash", Fremhash, Sremhash, 2, 2, 0,
 DEFUN ("maphash", Fmaphash, Smaphash, 2, 2, 0,
        doc: /* Call FUNCTION for all entries in hash table TABLE.
 FUNCTION is called with two arguments, KEY and VALUE.
+It should not alter TABLE in any way other than using `puthash' to
+set a new value for KEY, or `remhash' to remove KEY.
 `maphash' always returns nil.  */)
   (Lisp_Object function, Lisp_Object table)
 {