branch: externals/dash
commit d17fc9aa7c6560ad2a48788227e28ff27a5930db
Author: Basil L. Contovounesios <conto...@tcd.ie>
Commit: Basil L. Contovounesios <conto...@tcd.ie>
Simplify -annotate
* dash.el (--annotate, -annotate): Simplify implementation, and
rewrite function in terms of the macro. Improve docstrings.
* dev/examples.el (-annotate): Extend tests.
* README.md:
* dash.texi: Regenerate docs.
---
README.md | 15 ++++++++++-----
dash.el | 25 ++++++++++++++++++-------
dash.texi | 17 +++++++++++------
dev/examples.el | 30 +++++++++++++++++++++++++++---
4 files changed, 66 insertions(+), 21 deletions(-)
diff --git a/README.md b/README.md
index 64789b69d1..43efd00539 100644
--- a/README.md
+++ b/README.md
@@ -467,13 +467,18 @@ For a side-effecting variant, see also
[`-each-indexed`](#-each-indexed-list-fn)
#### -annotate `(fn list)`
-Return a list of cons cells where each cell is `fn` applied to each
-element of `list` paired with the unmodified element of `list`.
+Pair each item in `list` with the result of passing it to `fn`.
+
+Return an alist of (`result` . `item`), where each `item` is the
+corresponding element of `list`, and `result` is the value obtained
+by calling `fn` on `item`.
+
+This function's anaphoric counterpart is `--annotate`.
```el
-(-annotate '1+ '(1 2 3)) ;; => ((2 . 1) (3 . 2) (4 . 3))
-(-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) ;; => ((5 "h"
"e" "l" "l" "o") (2 "hello" "world"))
-(--annotate (< 1 it) '(0 1 2 3)) ;; => ((nil . 0) (nil . 1) (t . 2) (t . 3))
+(-annotate #'1+ '(1 2 3)) ;; => ((2 . 1) (3 . 2) (4 . 3))
+(-annotate #'length '((f o o) (bar baz))) ;; => ((3 f o o) (2 bar baz))
+(--annotate (> it 1) '(0 1 2 3)) ;; => ((nil . 0) (nil . 1) (t . 2) (t . 3))
```
#### -splice `(pred fun list)`
diff --git a/dash.el b/dash.el
index ed3a15131f..3447016eeb 100644
--- a/dash.el
+++ b/dash.el
@@ -1714,15 +1714,26 @@ resulting LISTS."
(maxlen (apply #'max 0 lens)))
(--map (append it (make-list (- maxlen (pop lens)) fill-value)) lists)))
+(defmacro --annotate (form list)
+ "Pair each item in LIST with the result of evaluating FORM.
+
+Return an alist of (RESULT . ITEM), where each ITEM is the
+corresponding element of LIST, and RESULT is the value obtained
+by evaluating FORM with ITEM bound to `it'.
+
+This is the anaphoric counterpart to `-annotate'."
+ (declare (debug (form form)))
+ `(--map (cons ,form it) ,list))
+
(defun -annotate (fn list)
- "Return a list of cons cells where each cell is FN applied to each
-element of LIST paired with the unmodified element of LIST."
- (-zip (-map fn list) list))
+ "Pair each item in LIST with the result of passing it to FN.
-(defmacro --annotate (form list)
- "Anaphoric version of `-annotate'."
- (declare (debug (def-form form)))
- `(-annotate (lambda (it) (ignore it) ,form) ,list))
+Return an alist of (RESULT . ITEM), where each ITEM is the
+corresponding element of LIST, and RESULT is the value obtained
+by calling FN on ITEM.
+
+This function's anaphoric counterpart is `--annotate'."
+ (--annotate (funcall fn it) list))
(defun dash--table-carry (lists restore-lists &optional re)
"Helper for `-table' and `-table-flat'.
diff --git a/dash.texi b/dash.texi
index a38f20fd3a..72b7b712ca 100644
--- a/dash.texi
+++ b/dash.texi
@@ -360,20 +360,25 @@ For a side-effecting variant, see also
@code{-each-indexed} (@pxref{-each-indexe
@anchor{-annotate}
@defun -annotate (fn list)
-Return a list of cons cells where each cell is @var{fn} applied to each
-element of @var{list} paired with the unmodified element of @var{list}.
+Pair each item in @var{list} with the result of passing it to @var{fn}.
+
+Return an alist of (@var{result} . @var{item}), where each @var{item} is the
+corresponding element of @var{list}, and @var{result} is the value obtained
+by calling @var{fn} on @var{item}.
+
+This function's anaphoric counterpart is @code{--annotate}.
@example
@group
-(-annotate '1+ '(1 2 3))
+(-annotate #'1+ '(1 2 3))
@result{} ((2 . 1) (3 . 2) (4 . 3))
@end group
@group
-(-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world")))
- @result{} ((5 "h" "e" "l" "l" "o") (2 "hello" "world"))
+(-annotate #'length '((f o o) (bar baz)))
+ @result{} ((3 f o o) (2 bar baz))
@end group
@group
-(--annotate (< 1 it) '(0 1 2 3))
+(--annotate (> it 1) '(0 1 2 3))
@result{} ((nil . 0) (nil . 1) (t . 2) (t . 3))
@end group
@end example
diff --git a/dev/examples.el b/dev/examples.el
index 0b1ff173c5..54a8b237bd 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -101,9 +101,33 @@ new list."
(--map-indexed t '()) => '())
(defexamples -annotate
- (-annotate '1+ '(1 2 3)) => '((2 . 1) (3 . 2) (4 . 3))
- (-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) => '((5 .
("h" "e" "l" "l" "o")) (2 . ("hello" "world")))
- (--annotate (< 1 it) '(0 1 2 3)) => '((nil . 0) (nil . 1) (t . 2) (t . 3)))
+ (-annotate #'1+ '(1 2 3)) => '((2 . 1) (3 . 2) (4 . 3))
+ (-annotate #'length '((f o o) (bar baz))) => '((3 f o o) (2 bar baz))
+ (--annotate (> it 1) '(0 1 2 3)) => '((nil . 0) (nil . 1) (t . 2) (t . 3))
+ (--annotate nil ()) => ()
+ (--annotate nil '(a)) => '((nil . a))
+ (--annotate nil '((a))) => '((nil a))
+ (--annotate t ()) => ()
+ (--annotate t '(a)) => '((t . a))
+ (--annotate t '((a))) => '((t a))
+ (--annotate it ()) => ()
+ (--annotate it '(a)) => '((a . a))
+ (--annotate it '((a))) => '(((a) a))
+ (--annotate (list it) ()) => ()
+ (--annotate (list it) '(a)) => '(((a) . a))
+ (--annotate (list it) '((a))) => '((((a)) a))
+ (-annotate #'ignore ()) => ()
+ (-annotate #'ignore '(a)) => '((nil . a))
+ (-annotate #'ignore '((a))) => '((nil a))
+ (-annotate (-andfn) ()) => ()
+ (-annotate (-andfn) '(a)) => '((t . a))
+ (-annotate (-andfn) '((a))) => '((t a))
+ (-annotate #'identity ()) => ()
+ (-annotate #'identity '(a)) => '((a . a))
+ (-annotate #'identity '((a))) => '(((a) a))
+ (-annotate #'list ()) => ()
+ (-annotate #'list '(a)) => '(((a) . a))
+ (-annotate #'list '((a))) => '((((a)) a)))
(defexamples -splice
(-splice #'numberp (lambda (n) (list n n)) '(a 1 b 2)) => '(a 1 1 b 2 2)
