[elpa] externals/dash 1fce650 019/316: Add `-each-indexed` and an anaphoric equivalent (#178)

[ELPA Syncer]

branch: externals/dash
commit 1fce650170b974a3a76ad7150fe13ca0b9769d2d
Author: Wilfred Hughes <me@wilfred.me.uk>
Commit: Matus Goljer <dota.keys@gmail.com>

    Add `-each-indexed` and an anaphoric equivalent (#178)
    
    This adds `-each-indexed` and an anaphoric variant `--each-indexed`,
    equivalent to `-map-indexed`.
    
    Whilst `--each` already defines `it-index`, it's not documented. Having
    a separate version is more explicit and more discoverable because it's
    similarly named to `-map-indexed`.
    
    Fixes #175.
---
 README.md       | 16 ++++++++++++++++
 dash.el         | 14 +++++++++++++-
 dash.texi       | 22 ++++++++++++++++++++++
 dev/examples.el |  4 ++++
 4 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 04e14e5..3f54228 100644
--- a/README.md
+++ b/README.md
@@ -273,6 +273,7 @@ Functions iterating over lists for side-effect only.
 
 * [-each](#-each-list-fn) `(list fn)`
 * [-each-while](#-each-while-list-pred-fn) `(list pred fn)`
+* [-each-indexed](#-each-indexed-list-fn) `(list fn)`
 * [-dotimes](#-dotimes-num-fn) `(num fn)`
 
 ### Destructive operations
@@ -366,6 +367,8 @@ Return a new list consisting of the result of (`fn` index 
item) for each item in
 
 In the anaphoric form `--map-indexed`, the index is exposed as `it-index`.
 
+See also: [`-each-indexed`](#-each-indexed-list-fn).
+
 ```el
 (-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) ;; => '(1 1 1 1)
 (--map-indexed (- it it-index) '(1 2 3 4)) ;; => '(1 1 1 1)
@@ -2137,6 +2140,19 @@ Return nil, used for side-effects only.
 (let (s) (--each-while '(1 2 3 4) (< it 3) (!cons it s)) s) ;; => '(2 1)
 ```
 
+#### -each-indexed `(list fn)`
+
+Call (`fn` index item) for each item in `list`.
+
+In the anaphoric form `--each-indexed`, the index is exposed as `it-index`.
+
+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))
+```
+
 #### -dotimes `(num fn)`
 
 Repeatedly calls `fn` (presumably for side-effects) passing in integers from 0 
through `num-1`.
diff --git a/dash.el b/dash.el
index 7c8ed69..3e4c5e1 100644
--- a/dash.el
+++ b/dash.el
@@ -77,6 +77,16 @@ special values."
 
 (put '-each 'lisp-indent-function 1)
 
+(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 `it-index`.
+
+See also: `-map-indexed'."
+  (--each list (funcall fn it-index it)))
+
 (defmacro --each-while (list pred &rest body)
   "Anaphoric form of `-each-while'."
   (declare (debug (form form body))
@@ -317,7 +327,9 @@ If you want to select the original items satisfying a 
predicate use `-filter'."
 (defun -map-indexed (fn list)
   "Return a new list consisting of the result of (FN index item) for each item 
in LIST.
 
-In the anaphoric form `--map-indexed', the index is exposed as `it-index`."
+In the anaphoric form `--map-indexed', the index is exposed as `it-index`.
+
+See also: `-each-indexed'."
   (--map-indexed (funcall fn it-index it) list))
 
 (defmacro --map-when (pred rep list)
diff --git a/dash.texi b/dash.texi
index d9e735e..8eba942 100644
--- a/dash.texi
+++ b/dash.texi
@@ -300,6 +300,8 @@ Return a new list consisting of the result of (@var{fn} 
index item) for each ite
 
 In the anaphoric form @code{--map-indexed}, the index is exposed as `it-index`.
 
+See also: @code{-each-indexed} (@pxref{-each-indexed}).
+
 @example
 @group
 (-map-indexed (lambda (index item) (- item index)) '(1 2 3 4))
@@ -3181,6 +3183,26 @@ Return nil, used for side-effects only.
 @end example
 @end defun
 
+@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 
`it-index`.
+
+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)
+    @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)
+    @result{} '((c 2) (b 1) (a 0))
+@end group
+@end example
+@end defun
+
 @anchor{-dotimes}
 @defun -dotimes (num fn)
 Repeatedly calls @var{fn} (presumably for side-effects) passing in integers 
from 0 through @var{num-1}.
diff --git a/dev/examples.el b/dev/examples.el
index 7fa8528..8bf6a2e 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1002,6 +1002,10 @@ new list."
     (let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) s) 
=> '(4 2)
     (let (s) (--each-while '(1 2 3 4) (< it 3) (!cons it s)) s) => '(2 1))
 
+  (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)))
+
   (defexamples -dotimes
     (let (s) (-dotimes 3 (lambda (n) (!cons n s))) s) => '(2 1 0)
     (let (s) (--dotimes 5 (!cons it s)) s) => '(4 3 2 1 0)))