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 3d3fe3e3be2acc3b541d0f359d7c483714fab93a..4270de664f16917afa443a7aa4151ba01be49de2 100644 (file)
--- 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 4531b23782473992134d6024751e54fccdb2dd45..f862c1470c4b34a2e66a5a6535c6c7222208503e 100644 (file)
--- 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)
 {