From: Richard M. Stallman <rms@gnu.org>
Date: Tue, 30 Sep 2003 13:00:23 +0000 (+0000)
Subject: (Association Lists): Clarify `assq-delete-all'.
X-Git-Tag: ttn-vms-21-2-B4~8676
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=66fd2c72334d7db3dfa38c3c7b875ecefa6cdd0f;p=emacs.git

(Association Lists): Clarify `assq-delete-all'.
---

diff --git a/lispref/lists.texi b/lispref/lists.texi
index b437916694f..5042d52d674 100644
--- a/lispref/lists.texi
+++ b/lispref/lists.texi
@@ -1670,14 +1670,19 @@ the associations of one copy without affecting the other:
 @defun assq-delete-all key alist
 @tindex assq-delete-all
 This function deletes from @var{alist} all the elements whose @sc{car}
-is @code{eq} to @var{key}.  It returns @var{alist}, modified
-in this way.  Note that it modifies the original list structure
-of @var{alist}.
+is @code{eq} to @var{key}, much as if you used @code{delq} to delete
+such each element one by one.  It returns the shortened alist, and
+often modifies the original list structure of @var{alist}.  For
+correct results, use the return value of @code{assq-delete-all} rather
+than looking at the saved value of @var{alist}.
 
 @example
-(assq-delete-all 'foo
-                 '((foo 1) (bar 2) (foo 3) (lose 4)))
+(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
+     @result{} ((foo 1) (bar 2) (foo 3) (lose 4))
+(assq-delete-all 'foo alist)
      @result{} ((bar 2) (lose 4))
+alist
+     @result{} ((foo 1) (bar 2) (lose 4))
 @end example
 @end defun