From 4eb81217cdf23e3f228ef3d95e7b5a0ceb95007c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Mattias=20Engdeg=C3=A5rd?= Date: Fri, 19 Jan 2024 15:52:13 +0100 Subject: [PATCH] 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) --- doc/lispref/hash.texi | 4 ++++ src/fns.c | 2 ++ 2 files changed, 6 insertions(+) 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) { -- 2.39.5