From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Tue, 26 Apr 2022 13:32:45 +0000 (+0200)
Subject: Mention caveats in the map-delete doc string
X-Git-Tag: emacs-29.0.90~1931^2~294
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=756b7cf5d9a817503437b3e8a9e8d912b7ee6c75;p=emacs.git

Mention caveats in the map-delete doc string

* lisp/emacs-lisp/map.el (map-delete): Mention how this has to be
used for lists (bug#25929).
---

diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el
index c53f253f87f..8c67d7c7a25 100644
--- a/lisp/emacs-lisp/map.el
+++ b/lisp/emacs-lisp/map.el
@@ -175,7 +175,17 @@ MAP can be an alist, plist, hash-table, or array."
 
 (cl-defgeneric map-delete (map key)
   "Delete KEY in-place from MAP and return MAP.
-Keys not present in MAP are ignored.")
+Keys not present in MAP are ignored.
+
+Note that if MAP is a list (either alist or plist), and you're
+deleting the final element in the list, the list isn't actually
+destructively modified (but the return value will reflect the
+deletion).  So if you're using this method on a list, you have to
+say
+
+  (setq map (map-delete map key))
+
+for this to work reliably.")
 
 (cl-defmethod map-delete ((map list) key)
   ;; FIXME: Signal map-not-inplace i.s.o returning a different list?