diff options
author | Michael Heerdegen <michael_heerdegen@web.de> | 2019-03-12 15:13:55 +0100 |
---|---|---|
committer | Michael Heerdegen <michael_heerdegen@web.de> | 2019-03-27 19:40:49 +0100 |
commit | 6dfd28c3201719cc284183a74dc1cc1344410905 (patch) | |
tree | 927de479e7371041350652b7bf094041758f5d4d | |
parent | 92acab73e0dd3921b53eac4f3fba327b7aa4d3aa (diff) | |
download | emacs-6dfd28c3201719cc284183a74dc1cc1344410905.tar.gz |
Improve documentation of 'alist-get' (Bug#34708)
* lisp/subr.el (alist-get): Enhance part of docstring explaining usage
in place expressions.
-rw-r--r-- | lisp/subr.el | 26 |
1 files 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) |