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

@@ -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)`

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'.

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

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)