From 6dfd28c3201719cc284183a74dc1cc1344410905 Mon Sep 17 00:00:00 2001 From: Michael Heerdegen Date: Tue, 12 Mar 2019 15:13:55 +0100 Subject: [PATCH] Improve documentation of 'alist-get' (Bug#34708) * lisp/subr.el (alist-get): Enhance part of docstring explaining usage in place expressions. --- lisp/subr.el | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/lisp/subr.el b/lisp/subr.el index 6dc53cd7201..f1a1dddd81c 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -756,9 +756,31 @@ Elements of ALIST that are not conses are ignored." If KEY is not found in ALIST, return DEFAULT. Use TESTFN to lookup in the alist if non-nil. Otherwise, use `assq'. -This is a generalized variable suitable for use with `setf'. +You can use `alist-get' in PLACE expressions. This will modify +an existing association (more precisely, the first one if +multiple exist), or add a new element to the beginning of ALIST, +destructively modifying the list stored in ALIST. + +Example: + + (setq foo '((a . 0))) + (setf (alist-get 'a foo) 1 + (alist-get 'b foo) 2) + + foo => ((b . 2) (a . 1)) + + When using it to set a value, optional argument REMOVE non-nil -means to remove KEY from ALIST if the new value is `eql' to DEFAULT." +means to remove KEY from ALIST if the new value is `eql' to +DEFAULT (more precisely the first found association will be +deleted from the alist). + +Example: + + (setq foo '((a . 1) (b . 2))) + (setf (alist-get 'b foo nil 'remove) nil) + + foo => ((a . 1))" (ignore remove) ;;Silence byte-compiler. (let ((x (if (not testfn) (assq key alist) -- 2.39.5