[elpa] externals/dash 92393c7 220/316: Clean up core definitions

[ELPA Syncer]

branch: externals/dash
commit 92393c73e0595114210567ece36112817d98555f
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Clean up core definitions
    
    * dash.el (--each, --each-while, --each-r, --each-r-while): Protect
    it and it-index from modification and unused lexical variable
    warnings.
    (-each): Use mapc for speed.
    (-each-indexed, -each-while, -each-r, -each-r-while, --dotimes)
    (-dotimes, -map): Improve docstrings and make them more consistent.
    (--map): Rewrite as a loop to avoid funcall overhead and unused
    lexical variable warnings.
    
    * dev/examples.el (three-letters): Remove function.
    (Maps): Fix grammar.
    (Unfolding): Wrap description over multiple lines.
    (Side effects): No need to hyphenate side effects.
    (-map, -each, --each-while, -each-indexed, -each-r, -each-r-while)
    (-dotimes): Simplify and extend tests.
    
    * README.md:
    * dash.texi: Regenerate docs.
---
 README.md       |  83 ++++++++++++++++-----------
 dash.el         | 171 ++++++++++++++++++++++++++++++++++----------------------
 dash.texi       |  96 ++++++++++++++++++-------------
 dev/examples.el |  69 +++++++++++++++--------
 4 files changed, 257 insertions(+), 162 deletions(-)

diff --git a/README.md b/README.md
index c8baacf..ec1b8a7 100644
--- a/README.md
+++ b/README.md
@@ -94,7 +94,7 @@ This demonstrates the utility of both versions.
 
 Functions in this category take a transforming function, which
 is then applied sequentially to each or selected elements of the
-input list.  The results are collected in order and returned as
+input list.  The results are collected in order and returned as a
 new list.
 
 * [-map](#-map-fn-list) `(fn list)`
@@ -178,7 +178,8 @@ Functions reducing lists into single value.
 ### Unfolding
 
 
-Operations dual to reductions, building lists from a seed value rather than 
consuming a list to produce a single value.
+Operations dual to reductions, building lists from a seed
+value rather than consuming a list to produce a single value.
 
 * [-iterate](#-iterate-fun-init-n) `(fun init n)`
 * [-unfold](#-unfold-fun-seed) `(fun seed)`
@@ -315,10 +316,10 @@ Convenient versions of `let` and `let*` constructs 
combined with flow control.
 * [-lambda](#-lambda-match-form-rest-body) `(match-form &rest body)`
 * [-setq](#-setq-rest-forms) `(&rest forms)`
 
-### Side-effects
+### Side effects
 
 
-Functions iterating over lists for side-effect only.
+Functions iterating over lists for side effect only.
 
 * [-each](#-each-list-fn) `(list fn)`
 * [-each-while](#-each-while-list-pred-fn) `(list pred fn)`
@@ -359,16 +360,17 @@ These combinators require Emacs 24 for its lexical scope. 
So they are offered in
 
 Functions in this category take a transforming function, which
 is then applied sequentially to each or selected elements of the
-input list.  The results are collected in order and returned as
+input list.  The results are collected in order and returned as a
 new list.
 
 #### -map `(fn list)`
 
-Return a new list consisting of the result of applying `fn` to the items in 
`list`.
+Apply `fn` to each item in `list` and return the list of results.
+This function's anaphoric counterpart is `--map`.
 
 ```el
 (-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => '(1 4 9 16)
-(-map 'square '(1 2 3 4)) ;; => '(1 4 9 16)
+(-map #'1+ '(1 2 3 4)) ;; => '(2 3 4 5)
 (--map (* it it) '(1 2 3 4)) ;; => '(1 4 9 16)
 ```
 
@@ -1160,7 +1162,8 @@ comparing them.
 ## Unfolding
 
 
-Operations dual to reductions, building lists from a seed value rather than 
consuming a list to produce a single value.
+Operations dual to reductions, building lists from a seed
+value rather than consuming a list to produce a single value.
 
 #### -iterate `(fun init n)`
 
@@ -2588,72 +2591,84 @@ multiple assignments it does not cause unexpected side 
effects.
 ```
 
 
-## Side-effects
+## Side effects
 
 
-Functions iterating over lists for side-effect only.
+Functions iterating over lists for side effect only.
 
 #### -each `(list fn)`
 
-Call `fn` with every item in `list`. Return nil, used for side-effects only.
+Call `fn` on each element of `list`.
+Return nil; this function is intended for side effects.
+Its anaphoric counterpart is `--each`.  For access to the current
+element's index in `list`, see [`-each-indexed`](#-each-indexed-list-fn).
 
 ```el
-(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) ;; => nil
-(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))) s) ;; => '(3 
2 1)
-(let (s) (--each '(1 2 3) (setq s (cons it s))) s) ;; => '(3 2 1)
+(let (l) (-each '(1 2 3) (lambda (x) (push x l))) l) ;; => '(3 2 1)
+(let (l) (--each '(1 2 3) (push it l)) l) ;; => '(3 2 1)
+(-each '(1 2 3) #'identity) ;; => nil
 ```
 
 #### -each-while `(list pred fn)`
 
-Call `fn` with every item in `list` while (`pred` item) is non-nil.
-Return nil, used for side-effects only.
+Call `fn` on each `item` in `list`, while (`pred` `item`) is non-nil.
+Once an `item` is reached for which `pred` returns nil, `fn` is no
+longer called.  Return nil; this function is intended for side
+effects.
+Its anaphoric counterpart is `--each-while`.
 
 ```el
-(let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (push item s))) s) ;; 
=> '(4 2)
-(let (s) (--each-while '(1 2 3 4) (< it 3) (push it s)) s) ;; => '(2 1)
+(let (l) (-each-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l) ;; => '(4 
2)
+(let (l) (--each-while '(1 2 3 4) (< it 3) (push it l)) l) ;; => '(2 1)
 (let ((s 0)) (--each-while '(1 3 4 5) (odd? it) (setq s (+ s it))) s) ;; => 4
 ```
 
 #### -each-indexed `(list fn)`
 
-Call (`fn` index item) for each item in `list`.
-
-In the anaphoric form `--each-indexed`, the index is exposed as symbol 
`it-index`.
-
+Call `fn` on each index and element of `list`.
+For each `item` at `index` in `list`, call (funcall `fn` `index` `item`).
+Return nil; this function is intended for side effects.
 See also: [`-map-indexed`](#-map-indexed-fn-list).
 
 ```el
-(let (s) (-each-indexed '(a b c) (lambda (index item) (setq s (cons (list item 
index) s)))) s) ;; => '((c 2) (b 1) (a 0))
-(let (s) (--each-indexed '(a b c) (setq s (cons (list it it-index) s))) s) ;; 
=> '((c 2) (b 1) (a 0))
+(let (l) (-each-indexed '(a b c) (lambda (i x) (push (list x i) l))) l) ;; => 
'((c 2) (b 1) (a 0))
+(let (l) (--each-indexed '(a b c) (push (list it it-index) l)) l) ;; => '((c 
2) (b 1) (a 0))
+(let (l) (--each-indexed nil (push it l)) l) ;; => nil
 ```
 
 #### -each-r `(list fn)`
 
-Call `fn` with every item in `list` in reversed order.
- Return nil, used for side-effects only.
+Call `fn` on each element of `list` in reversed order.
+Return nil; this function is intended for side effects.
+Its anaphoric counterpart is `--each-r`.
 
 ```el
-(let (s) (-each-r '(1 2 3) (lambda (item) (setq s (cons item s))))) ;; => nil
-(let (s) (-each-r '(1 2 3) (lambda (item) (setq s (cons item s)))) s) ;; => 
'(1 2 3)
-(let (s) (--each-r '(1 2 3) (setq s (cons it s))) s) ;; => '(1 2 3)
+(let (l) (-each-r '(1 2 3) (lambda (x) (push x l))) l) ;; => '(1 2 3)
+(let (l) (--each-r '(1 2 3) (push it l)) l) ;; => '(1 2 3)
+(-each-r '(1 2 3) #'identity) ;; => nil
 ```
 
 #### -each-r-while `(list pred fn)`
 
-Call `fn` with every item in reversed `list` while (`pred` item) is non-nil.
-Return nil, used for side-effects only.
+Call `fn` on each `item` in reversed `list`, while (`pred` `item`) is non-nil.
+Once an `item` is reached for which `pred` returns nil, `fn` is no
+longer called.  Return nil; this function is intended for side
+effects.
+Its anaphoric counterpart is `--each-r-while`.
 
 ```el
-(let (s) (-each-r-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) s) 
;; => '(6)
-(let (s) (--each-r-while '(1 2 3 4) (>= it 3) (!cons it s)) s) ;; => '(3 4)
+(let (l) (-each-r-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l) ;; => 
'(6)
+(let (l) (--each-r-while '(1 2 3 4) (>= it 3) (push it l)) l) ;; => '(3 4)
+(let ((s 0)) (--each-r-while '(1 2 3 5) (odd? it) (setq s (+ s it))) s) ;; => 8
 ```
 
 #### -dotimes `(num fn)`
 
-Call `fn` `num` times, presumably for side-effects.
+Call `fn` `num` times, presumably for side effects.
 `fn` is called with a single argument on successive integers
 running from 0, inclusive, to `num`, exclusive.  `fn` is not called
 if `num` is less than 1.
+This function's anaphoric counterpart is `--dotimes`.
 
 ```el
 (let (s) (-dotimes 3 (lambda (n) (push n s))) s) ;; => '(2 1 0)
diff --git a/dash.el b/dash.el
index f0d56a9..e65a8d0 100644
--- a/dash.el
+++ b/dash.el
@@ -50,105 +50,132 @@
   `(setq ,list (cdr ,list)))
 
 (defmacro --each (list &rest body)
-  "Anaphoric form of `-each'."
-  (declare (debug (form body))
-           (indent 1))
-  (let ((l (make-symbol "list")))
+  "Evaluate BODY for each element of LIST and return nil.
+Each element of LIST in turn is bound to `it' and its index
+within LIST to `it-index' before evaluating BODY.
+This is the anaphoric counterpart to `-each'."
+  (declare (debug (form body)) (indent 1))
+  (let ((l (make-symbol "list"))
+        (i (make-symbol "i")))
     `(let ((,l ,list)
-           (it-index 0))
+           (,i 0)
+           it it-index)
+       (ignore it it-index)
        (while ,l
-         (let ((it (car ,l)))
-           ,@body)
-         (setq it-index (1+ it-index))
-         (!cdr ,l)))))
+         (setq it (pop ,l) it-index ,i ,i (1+ ,i))
+         ,@body))))
 
 (defun -each (list fn)
-  "Call FN with every item in LIST. Return nil, used for side-effects only."
+  "Call FN on each element of LIST.
+Return nil; this function is intended for side effects.
+Its anaphoric counterpart is `--each'.  For access to the current
+element's index in LIST, see `-each-indexed'."
   (declare (indent 1))
-  (--each list (funcall fn it)))
+  (ignore (mapc fn list)))
 
 (defalias '--each-indexed '--each)
 
 (defun -each-indexed (list fn)
-  "Call (FN index item) for each item in LIST.
-
-In the anaphoric form `--each-indexed', the index is exposed as symbol 
`it-index'.
-
+  "Call FN on each index and element of LIST.
+For each ITEM at INDEX in LIST, call (funcall FN INDEX ITEM).
+Return nil; this function is intended for side effects.
 See also: `-map-indexed'."
   (declare (indent 1))
   (--each list (funcall fn it-index it)))
 
 (defmacro --each-while (list pred &rest body)
-  "Anaphoric form of `-each-while'."
-  (declare (debug (form form body))
-           (indent 2))
-  (let ((l (make-symbol "list")))
+  "Evaluate BODY for each item in LIST, while PRED evaluates to non-nil.
+Each element of LIST in turn is bound to `it' and its index
+within LIST to `it-index' before evaluating PRED or BODY.  Once
+an element is reached for which PRED evaluates to nil, no further
+BODY is evaluated.  The return value is always nil.
+This is the anaphoric counterpart to `-each-while'."
+  (declare (debug (form form body)) (indent 2))
+  (let ((l (make-symbol "list"))
+        (i (make-symbol "i"))
+        (elt (make-symbol "elt")))
     `(let ((,l ,list)
-           (it-index 0)
-           it)
-       (ignore it)
-       (while (when ,l
-                (setq it (pop ,l))
-                ,pred)
-         ,@body
-         (setq it-index (1+ it-index))))))
+           (,i 0)
+           ,elt it it-index)
+       (ignore it it-index)
+       (while (and ,l (setq ,elt (pop ,l) it ,elt it-index ,i) ,pred)
+         (setq it ,elt it-index ,i ,i (1+ ,i))
+         ,@body))))
 
 (defun -each-while (list pred fn)
-  "Call FN with every item in LIST while (PRED item) is non-nil.
-Return nil, used for side-effects only."
+  "Call FN on each ITEM in LIST, while (PRED ITEM) is non-nil.
+Once an ITEM is reached for which PRED returns nil, FN is no
+longer called.  Return nil; this function is intended for side
+effects.
+Its anaphoric counterpart is `--each-while'."
   (declare (indent 2))
   (--each-while list (funcall pred it) (funcall fn it)))
 
 (defmacro --each-r (list &rest body)
-  "Anaphoric form of `-each-r'."
-  (declare (debug (form body))
-           (indent 1))
-  (let ((v (make-symbol "vector")))
-    ;; Implementation note: building vector is considerably faster
+  "Evaluate BODY for each element of LIST in reversed order.
+Each element of LIST in turn, starting at its end, is bound to
+`it' and its index within LIST to `it-index' before evaluating
+BODY.  The return value is always nil.
+This is the anaphoric counterpart to `-each-r'."
+  (declare (debug (form body)) (indent 1))
+  (let ((v (make-symbol "vector"))
+        (i (make-symbol "i")))
+    ;; Implementation note: building a vector is considerably faster
     ;; than building a reversed list (vector takes less memory, so
-    ;; there is less GC), plus length comes naturally.  In-place
-    ;; 'nreverse' would be faster still, but BODY would be able to see
-    ;; that, even if modification was reversed before we return.
+    ;; there is less GC), plus `length' comes naturally.  In-place
+    ;; `nreverse' would be faster still, but BODY would be able to see
+    ;; that, even if the modification was undone before we return.
     `(let* ((,v (vconcat ,list))
-            (it-index (length ,v))
-            it)
-       (while (> it-index 0)
-         (setq it-index (1- it-index))
-         (setq it (aref ,v it-index))
+            (,i (length ,v))
+            it it-index)
+       (ignore it it-index)
+       (while (> ,i 0)
+         (setq ,i (1- ,i) it-index ,i it (aref ,v ,i))
          ,@body))))
 
 (defun -each-r (list fn)
-  "Call FN with every item in LIST in reversed order.
- Return nil, used for side-effects only."
+  "Call FN on each element of LIST in reversed order.
+Return nil; this function is intended for side effects.
+Its anaphoric counterpart is `--each-r'."
   (--each-r list (funcall fn it)))
 
 (defmacro --each-r-while (list pred &rest body)
-  "Anaphoric form of `-each-r-while'."
-  (declare (debug (form form body))
-           (indent 2))
-  (let ((v (make-symbol "vector")))
+  "Eval BODY for each item in reversed LIST, while PRED evals to non-nil.
+Each element of LIST in turn, starting at its end, is bound to
+`it' and its index within LIST to `it-index' before evaluating
+PRED or BODY.  Once an element is reached for which PRED
+evaluates to nil, no further BODY is evaluated.  The return value
+is always nil.
+This is the anaphoric counterpart to `-each-r-while'."
+  (declare (debug (form form body)) (indent 2))
+  (let ((v (make-symbol "vector"))
+        (i (make-symbol "i"))
+        (elt (make-symbol "elt")))
     `(let* ((,v (vconcat ,list))
-            (it-index (length ,v))
-            it)
-       (while (> it-index 0)
-         (setq it-index (1- it-index))
-         (setq it (aref ,v it-index))
-         (if (not ,pred)
-             (setq it-index -1)
-           ,@body)))))
+            (,i (length ,v))
+            ,elt it it-index)
+       (ignore it it-index)
+       (while (when (> ,i 0)
+                (setq ,i (1- ,i) it-index ,i)
+                (setq ,elt (aref ,v ,i) it ,elt)
+                ,pred)
+         (setq it-index ,i it ,elt)
+         ,@body))))
 
 (defun -each-r-while (list pred fn)
-  "Call FN with every item in reversed LIST while (PRED item) is non-nil.
-Return nil, used for side-effects only."
+  "Call FN on each ITEM in reversed LIST, while (PRED ITEM) is non-nil.
+Once an ITEM is reached for which PRED returns nil, FN is no
+longer called.  Return nil; this function is intended for side
+effects.
+Its anaphoric counterpart is `--each-r-while'."
   (--each-r-while list (funcall pred it) (funcall fn it)))
 
 (defmacro --dotimes (num &rest body)
-  "Evaluate BODY NUM times, presumably for side-effects.
+  "Evaluate BODY NUM times, presumably for side effects.
 BODY is evaluated with the local variable `it' temporarily bound
 to successive integers running from 0, inclusive, to NUM,
 exclusive.  BODY is not evaluated if NUM is less than 1.
-
-This is the anaphoric version of `-dotimes'."
+This is the anaphoric counterpart to `-dotimes'."
   (declare (debug (form body)) (indent 1))
   (let ((n (make-symbol "num"))
         (i (make-symbol "i")))
@@ -161,21 +188,33 @@ This is the anaphoric version of `-dotimes'."
          ,@body))))
 
 (defun -dotimes (num fn)
-  "Call FN NUM times, presumably for side-effects.
+  "Call FN NUM times, presumably for side effects.
 FN is called with a single argument on successive integers
 running from 0, inclusive, to NUM, exclusive.  FN is not called
-if NUM is less than 1."
+if NUM is less than 1.
+This function's anaphoric counterpart is `--dotimes'."
   (declare (indent 1))
   (--dotimes num (funcall fn it)))
 
 (defun -map (fn list)
-  "Return a new list consisting of the result of applying FN to the items in 
LIST."
+  "Apply FN to each item in LIST and return the list of results.
+This function's anaphoric counterpart is `--map'."
   (mapcar fn list))
 
 (defmacro --map (form list)
-  "Anaphoric form of `-map'."
+  "Eval FORM for each item in LIST and return the list of results.
+Each element of LIST in turn is bound to `it' before evaluating
+BODY.
+This is the anaphoric counterpart to `-map'."
   (declare (debug (form form)))
-  `(mapcar (lambda (it) ,form) ,list))
+  (let ((l (make-symbol "list"))
+        (r (make-symbol "res")))
+    `(let ((,l ,list) ,r it)
+       (ignore it)
+       (while ,l
+         (setq it (pop ,l))
+         (push ,form ,r))
+       (nreverse ,r))))
 
 (defmacro --reduce-from (form initial-value list)
   "Anaphoric form of `-reduce-from'."
diff --git a/dash.texi b/dash.texi
index c3f0bff..3aea063 100644
--- a/dash.texi
+++ b/dash.texi
@@ -80,7 +80,7 @@ Functions
 * Tree operations::
 * Threading macros::
 * Binding::
-* Side-effects::
+* Side effects::
 * Destructive operations::
 * Function combinators::
 
@@ -216,7 +216,7 @@ example, which demonstrates the utility of both versions.
 * Tree operations::
 * Threading macros::
 * Binding::
-* Side-effects::
+* Side effects::
 * Destructive operations::
 * Function combinators::
 @end menu
@@ -228,13 +228,14 @@ example, which demonstrates the utility of both versions.
 
 Functions in this category take a transforming function, which
 is then applied sequentially to each or selected elements of the
-input list.  The results are collected in order and returned as
+input list.  The results are collected in order and returned as a
 new list.
 
 
 @anchor{-map}
 @defun -map (fn list)
-Return a new list consisting of the result of applying @var{fn} to the items 
in @var{list}.
+Apply @var{fn} to each item in @var{list} and return the list of results.
+This function's anaphoric counterpart is @code{--map}.
 
 @example
 @group
@@ -242,8 +243,8 @@ Return a new list consisting of the result of applying 
@var{fn} to the items in
     @result{} '(1 4 9 16)
 @end group
 @group
-(-map 'square '(1 2 3 4))
-    @result{} '(1 4 9 16)
+(-map #'1+ '(1 2 3 4))
+    @result{} '(2 3 4 5)
 @end group
 @group
 (--map (* it it) '(1 2 3 4))
@@ -1603,7 +1604,8 @@ comparing them.
 @section Unfolding
 
 
-Operations dual to reductions, building lists from a seed value rather than 
consuming a list to produce a single value.
+Operations dual to reductions, building lists from a seed
+value rather than consuming a list to produce a single value.
 
 
 @anchor{-iterate}
@@ -3918,45 +3920,51 @@ multiple assignments it does not cause unexpected side 
effects.
 @end defmac
 
 
-@node Side-effects
-@section Side-effects
+@node Side effects
+@section Side effects
 
 
-Functions iterating over lists for side-effect only.
+Functions iterating over lists for side effect only.
 
 
 @anchor{-each}
 @defun -each (list fn)
-Call @var{fn} with every item in @var{list}. Return nil, used for side-effects 
only.
+Call @var{fn} on each element of @var{list}.
+Return nil; this function is intended for side effects.
+Its anaphoric counterpart is @code{--each}.  For access to the current
+element's index in @var{list}, see @code{-each-indexed} 
(@pxref{-each-indexed}).
 
 @example
 @group
-(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))))
-    @result{} nil
+(let (l) (-each '(1 2 3) (lambda (x) (push x l))) l)
+    @result{} '(3 2 1)
 @end group
 @group
-(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))) s)
+(let (l) (--each '(1 2 3) (push it l)) l)
     @result{} '(3 2 1)
 @end group
 @group
-(let (s) (--each '(1 2 3) (setq s (cons it s))) s)
-    @result{} '(3 2 1)
+(-each '(1 2 3) #'identity)
+    @result{} nil
 @end group
 @end example
 @end defun
 
 @anchor{-each-while}
 @defun -each-while (list pred fn)
-Call @var{fn} with every item in @var{list} while (@var{pred} item) is non-nil.
-Return nil, used for side-effects only.
+Call @var{fn} on each @var{item} in @var{list}, while (@var{pred} @var{item}) 
is non-nil.
+Once an @var{item} is reached for which @var{pred} returns nil, @var{fn} is no
+longer called.  Return nil; this function is intended for side
+effects.
+Its anaphoric counterpart is @code{--each-while}.
 
 @example
 @group
-(let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (push item s))) s)
+(let (l) (-each-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l)
     @result{} '(4 2)
 @end group
 @group
-(let (s) (--each-while '(1 2 3 4) (< it 3) (push it s)) s)
+(let (l) (--each-while '(1 2 3 4) (< it 3) (push it l)) l)
     @result{} '(2 1)
 @end group
 @group
@@ -3968,68 +3976,80 @@ Return nil, used for side-effects only.
 
 @anchor{-each-indexed}
 @defun -each-indexed (list fn)
-Call (@var{fn} index item) for each item in @var{list}.
-
-In the anaphoric form @code{--each-indexed}, the index is exposed as symbol 
@code{it-index}.
-
+Call @var{fn} on each index and element of @var{list}.
+For each @var{item} at @var{index} in @var{list}, call (funcall @var{fn} 
@var{index} @var{item}).
+Return nil; this function is intended for side effects.
 See also: @code{-map-indexed} (@pxref{-map-indexed}).
 
 @example
 @group
-(let (s) (-each-indexed '(a b c) (lambda (index item) (setq s (cons (list item 
index) s)))) s)
+(let (l) (-each-indexed '(a b c) (lambda (i x) (push (list x i) l))) l)
     @result{} '((c 2) (b 1) (a 0))
 @end group
 @group
-(let (s) (--each-indexed '(a b c) (setq s (cons (list it it-index) s))) s)
+(let (l) (--each-indexed '(a b c) (push (list it it-index) l)) l)
     @result{} '((c 2) (b 1) (a 0))
 @end group
+@group
+(let (l) (--each-indexed nil (push it l)) l)
+    @result{} nil
+@end group
 @end example
 @end defun
 
 @anchor{-each-r}
 @defun -each-r (list fn)
-Call @var{fn} with every item in @var{list} in reversed order.
- Return nil, used for side-effects only.
+Call @var{fn} on each element of @var{list} in reversed order.
+Return nil; this function is intended for side effects.
+Its anaphoric counterpart is @code{--each-r}.
 
 @example
 @group
-(let (s) (-each-r '(1 2 3) (lambda (item) (setq s (cons item s)))))
-    @result{} nil
+(let (l) (-each-r '(1 2 3) (lambda (x) (push x l))) l)
+    @result{} '(1 2 3)
 @end group
 @group
-(let (s) (-each-r '(1 2 3) (lambda (item) (setq s (cons item s)))) s)
+(let (l) (--each-r '(1 2 3) (push it l)) l)
     @result{} '(1 2 3)
 @end group
 @group
-(let (s) (--each-r '(1 2 3) (setq s (cons it s))) s)
-    @result{} '(1 2 3)
+(-each-r '(1 2 3) #'identity)
+    @result{} nil
 @end group
 @end example
 @end defun
 
 @anchor{-each-r-while}
 @defun -each-r-while (list pred fn)
-Call @var{fn} with every item in reversed @var{list} while (@var{pred} item) 
is non-nil.
-Return nil, used for side-effects only.
+Call @var{fn} on each @var{item} in reversed @var{list}, while (@var{pred} 
@var{item}) is non-nil.
+Once an @var{item} is reached for which @var{pred} returns nil, @var{fn} is no
+longer called.  Return nil; this function is intended for side
+effects.
+Its anaphoric counterpart is @code{--each-r-while}.
 
 @example
 @group
-(let (s) (-each-r-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) s)
+(let (l) (-each-r-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l)
     @result{} '(6)
 @end group
 @group
-(let (s) (--each-r-while '(1 2 3 4) (>= it 3) (!cons it s)) s)
+(let (l) (--each-r-while '(1 2 3 4) (>= it 3) (push it l)) l)
     @result{} '(3 4)
 @end group
+@group
+(let ((s 0)) (--each-r-while '(1 2 3 5) (odd? it) (setq s (+ s it))) s)
+    @result{} 8
+@end group
 @end example
 @end defun
 
 @anchor{-dotimes}
 @defun -dotimes (num fn)
-Call @var{fn} @var{num} times, presumably for side-effects.
+Call @var{fn} @var{num} times, presumably for side effects.
 @var{fn} is called with a single argument on successive integers
 running from 0, inclusive, to @var{num}, exclusive.  @var{fn} is not called
 if @var{num} is less than 1.
+This function's anaphoric counterpart is @code{--dotimes}.
 
 @example
 @group
diff --git a/dev/examples.el b/dev/examples.el
index c0bb494..a7a95ed 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -39,7 +39,6 @@
 (defun odd? (num) (= 1 (% num 2)))
 (defun even? (num) (= 0 (% num 2)))
 (defun square (num) (* num num))
-(defun three-letters () '("A" "B" "C"))
 
 (defun dash-expand:&hash-or-plist (key source)
   "Sample destructoring which works with plists and hash-tables."
@@ -60,14 +59,15 @@
 (def-example-group "Maps"
   "Functions in this category take a transforming function, which
 is then applied sequentially to each or selected elements of the
-input list.  The results are collected in order and returned as
+input list.  The results are collected in order and returned as a
 new list."
 
   (defexamples -map
     (-map (lambda (num) (* num num)) '(1 2 3 4)) => '(1 4 9 16)
-    (-map 'square '(1 2 3 4)) => '(1 4 9 16)
+    (-map #'1+ '(1 2 3 4)) => '(2 3 4 5)
     (--map (* it it) '(1 2 3 4)) => '(1 4 9 16)
-    (--map (concat it it) (three-letters)) => '("AA" "BB" "CC"))
+    (--map it ()) => ()
+    (-map #'identity ()) => ())
 
   (defexamples -map-when
     (-map-when 'even? 'square '(1 2 3 4)) => '(1 4 3 16)
@@ -501,8 +501,8 @@ new list."
     (--max-by (> (length it) (length other)) '((1 2 3) (2) (3 2))) => '(1 2 
3)))
 
 (def-example-group "Unfolding"
-  "Operations dual to reductions, building lists from a seed value rather than 
\
-consuming a list to produce a single value."
+  "Operations dual to reductions, building lists from a seed
+value rather than consuming a list to produce a single value."
 
   (defexamples -iterate
     (-iterate #'1+ 1 10) => '(1 2 3 4 5 6 7 8 9 10)
@@ -1332,43 +1332,64 @@ consuming a list to produce a single value."
     (-setq (a b (&plist 'x x 'y y)) (list 1 2 (list 'x 3 'y 4))
            z x) => 3))
 
-(def-example-group "Side-effects"
-  "Functions iterating over lists for side-effect only."
+(def-example-group "Side effects"
+  "Functions iterating over lists for side effect only."
 
   (defexamples -each
-    (let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) => nil
-    (let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))) s) => '(3 
2 1)
-    (let (s) (--each '(1 2 3) (setq s (cons it s))) s) => '(3 2 1)
-    (let (s) (--each (reverse (three-letters)) (setq s (cons it s))) s) => 
'("A" "B" "C"))
+    (let (l) (-each '(1 2 3) (lambda (x) (push x l))) l) => '(3 2 1)
+    (let (l) (--each '(1 2 3) (push it l)) l) => '(3 2 1)
+    (-each '(1 2 3) #'identity) => nil
+    (--each '(1 2 3) it) => nil
+    (--each '(1 2 3) nil) => nil
+    (let (l) (-each () (lambda (x) (push x l))) l) => ()
+    (let (l) (--each () (push it l)) l) => ()
+    (let (l) (--each '(1 2 3) (push it l) (setq it-index -1)) l) => '(3 2 1))
 
   (defexamples -each-while
-    (let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (push item s))) s) 
=> '(4 2)
-    (let (s) (--each-while '(1 2 3 4) (< it 3) (push it s)) s) => '(2 1)
+    (let (l) (-each-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l) => 
'(4 2)
+    (let (l) (--each-while '(1 2 3 4) (< it 3) (push it l)) l) => '(2 1)
     (let ((s 0)) (--each-while '(1 3 4 5) (odd? it) (setq s (+ s it))) s) => 4
+    (let (s) (-each-while () (lambda (_) t) (lambda (_) (setq s t))) s) => nil
     (let (s) (--each-while () t (setq s t)) s) => nil
     (let (s) (--each-while '(1) t (setq s it)) s) => 1
-    (let (s) (--each-while '(1) nil (setq s it)) s) => nil)
+    (let (s) (--each-while '(1) nil (setq s it)) s) => nil
+    (let (s) (--each-while '(1) (setq it t) (setq s it)) s) => 1
+    (--each-while '(1) t t) => nil)
 
   (defexamples -each-indexed
-    (let (s) (-each-indexed '(a b c) (lambda (index item) (setq s (cons (list 
item index) s)))) s) => '((c 2) (b 1) (a 0))
-    (let (s) (--each-indexed '(a b c) (setq s (cons (list it it-index) s))) s) 
=> '((c 2) (b 1) (a 0)))
+    (let (l) (-each-indexed '(a b c) (lambda (i x) (push (list x i) l))) l) => 
'((c 2) (b 1) (a 0))
+    (let (l) (--each-indexed '(a b c) (push (list it it-index) l)) l) => '((c 
2) (b 1) (a 0))
+    (let (l) (--each-indexed () (push it l)) l) => ()
+    (let (l) (-each-indexed () (lambda (_ x) (push x l))) l) => ())
 
   (defexamples -each-r
-    (let (s) (-each-r '(1 2 3) (lambda (item) (setq s (cons item s))))) => nil
-    (let (s) (-each-r '(1 2 3) (lambda (item) (setq s (cons item s)))) s) => 
'(1 2 3)
-    (let (s) (--each-r '(1 2 3) (setq s (cons it s))) s) => '(1 2 3)
-    (let (s) (--each-r (reverse (three-letters)) (setq s (cons it s))) s) => 
'("C" "B" "A"))
+    (let (l) (-each-r '(1 2 3) (lambda (x) (push x l))) l) => '(1 2 3)
+    (let (l) (--each-r '(1 2 3) (push it l)) l) => '(1 2 3)
+    (-each-r '(1 2 3) #'identity) => nil
+    (--each-r '(1 2 3) it) => nil
+    (--each-r '(1 2 3) nil) => nil
+    (let (l) (--each-r '(1 2 3) (push it l) (setq it-index -1)) l) => '(1 2 3)
+    (let (l) (-each-r () (lambda (x) (push x l))) l) => ()
+    (let (l) (--each-r () (push it l)) l) => ())
 
   (defexamples -each-r-while
-    (let (s) (-each-r-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) 
s) => '(6)
-    (let (s) (--each-r-while '(1 2 3 4) (>= it 3) (!cons it s)) s) => '(3 4))
+    (let (l) (-each-r-while '(2 4 5 6) #'even? (lambda (x) (push x l))) l) => 
'(6)
+    (let (l) (--each-r-while '(1 2 3 4) (>= it 3) (push it l)) l) => '(3 4)
+    (let ((s 0)) (--each-r-while '(1 2 3 5) (odd? it) (setq s (+ s it))) s) => 
8
+    (let (s) (-each-r-while () (lambda (_) t) (lambda (_) (setq s t))) s) => 
nil
+    (let (s) (--each-r-while () t (setq s t)) s) => nil
+    (let (s) (--each-r-while '(1) t (setq s it)) s) => 1
+    (let (s) (--each-r-while '(1) nil (setq s it)) s) => nil
+    (let (s) (--each-r-while '(1) (setq it t) (setq s it)) s) => 1
+    (--each-r-while '(1) t t) => nil)
 
   (defexamples -dotimes
     (let (s) (-dotimes 3 (lambda (n) (push n s))) s) => '(2 1 0)
     (let (s) (-dotimes 0 (lambda (n) (push n s))) s) => ()
     (let (s) (--dotimes 5 (push it s)) s) => '(4 3 2 1 0)
     (let (s) (--dotimes 0 (push it s)) s) => ()
-    (let (s) (--dotimes 3 (push it s) (setq it -1)) s) => '(2 1 0)))
+    (let (s) (--dotimes 3 (push it s) (setq it -1)) s) => '(2 1 0)
+    (--dotimes 3 t) => nil))
 
 (def-example-group "Destructive operations" nil
   (defexamples !cons