[elpa] externals/dash ff5ed7a 261/316: Extend -keep docs and tests

[ELPA Syncer]

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

    Extend -keep docs and tests
    
    * dash.el (--keep): Extend docstring.  Prefer push over !cons.
    (-keep): Extend docstring.
    * dev/examples.el (-keep): Extend tests.
    
    * README.md:
    * dash.texi: Regenerate docs.
---
 README.md       | 13 +++++++------
 dash.el         | 16 +++++++++++-----
 dash.texi       | 13 +++++++------
 dev/examples.el | 11 ++++++++---
 4 files changed, 33 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 036cbcd..e87788b 100644
--- a/README.md
+++ b/README.md
@@ -749,14 +749,15 @@ Functions returning a modified copy of the input list.
 
 #### -keep `(fn list)`
 
-Return a new list of the non-nil results of applying `fn` to the items in 
`list`.
-
-If you want to select the original items satisfying a predicate use 
[`-filter`](#-filter-pred-list).
+Return a new list of the non-nil results of applying `fn` to each item in 
`list`.
+Like [`-filter`](#-filter-pred-list), but returns the non-nil results of `fn` 
instead of
+the corresponding elements of `list`.
+Its anaphoric counterpart is `--keep`.
 
 ```el
-(-keep 'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
-(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) ;; => '(40 
50 60)
-(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)
+(-keep #'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
+(-keep (lambda (n) (and (> n 3) (* 10 n))) '(1 2 3 4 5 6)) ;; => '(40 50 60)
+(--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)
 ```
 
 #### -concat `(&rest lists)`
diff --git a/dash.el b/dash.el
index a800a1d..84cfbe8 100644
--- a/dash.el
+++ b/dash.el
@@ -515,18 +515,24 @@ The comparison is done with `equal'.
 \n(fn ITEM LIST)")
 
 (defmacro --keep (form list)
-  "Anaphoric form of `-keep'."
+  "Eval FORM for each item in LIST and return the non-nil results.
+Like `--filter', but returns the non-nil results of FORM instead
+of the corresponding elements of LIST.  Each element of LIST in
+turn is bound to `it' and its index within LIST to `it-index'
+before evaluating FORM.
+This is the anaphoric counterpart to `-keep'."
   (declare (debug (form form)))
   (let ((r (make-symbol "result"))
         (m (make-symbol "mapped")))
     `(let (,r)
-       (--each ,list (let ((,m ,form)) (when ,m (!cons ,m ,r))))
+       (--each ,list (let ((,m ,form)) (when ,m (push ,m ,r))))
        (nreverse ,r))))
 
 (defun -keep (fn list)
-  "Return a new list of the non-nil results of applying FN to the items in 
LIST.
-
-If you want to select the original items satisfying a predicate use `-filter'."
+  "Return a new list of the non-nil results of applying FN to each item in 
LIST.
+Like `-filter', but returns the non-nil results of FN instead of
+the corresponding elements of LIST.
+Its anaphoric counterpart is `--keep'."
   (--keep (funcall fn it) list))
 
 (defun -non-nil (list)
diff --git a/dash.texi b/dash.texi
index 1d2ac44..4f0f487 100644
--- a/dash.texi
+++ b/dash.texi
@@ -872,21 +872,22 @@ Functions returning a modified copy of the input list.
 
 @anchor{-keep}
 @defun -keep (fn list)
-Return a new list of the non-nil results of applying @var{fn} to the items in 
@var{list}.
-
-If you want to select the original items satisfying a predicate use 
@code{-filter} (@pxref{-filter}).
+Return a new list of the non-nil results of applying @var{fn} to each item in 
@var{list}.
+Like @code{-filter} (@pxref{-filter}), but returns the non-nil results of 
@var{fn} instead of
+the corresponding elements of @var{list}.
+Its anaphoric counterpart is @code{--keep}.
 
 @example
 @group
-(-keep 'cdr '((1 2 3) (4 5) (6)))
+(-keep #'cdr '((1 2 3) (4 5) (6)))
     @result{} '((2 3) (5))
 @end group
 @group
-(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6))
+(-keep (lambda (n) (and (> n 3) (* 10 n))) '(1 2 3 4 5 6))
     @result{} '(40 50 60)
 @end group
 @group
-(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6))
+(--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6))
     @result{} '(40 50 60)
 @end group
 @end example
diff --git a/dev/examples.el b/dev/examples.el
index eb813f3..f376091 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -320,9 +320,14 @@ new list."
   "Functions returning a modified copy of the input list."
 
   (defexamples -keep
-    (-keep 'cdr '((1 2 3) (4 5) (6))) => '((2 3) (5))
-    (-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) => '(40 
50 60)
-    (--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) => '(40 50 60))
+    (-keep #'cdr '((1 2 3) (4 5) (6))) => '((2 3) (5))
+    (-keep (lambda (n) (and (> n 3) (* 10 n))) '(1 2 3 4 5 6)) => '(40 50 60)
+    (--keep (and (> it 3) (* 10 it)) '(1 2 3 4 5 6)) => '(40 50 60)
+    (-keep #'null '(nil)) => '(t)
+    (--keep it '(nil)) => '()
+    (--keep t '(nil)) => '(t)
+    (--keep t '()) => '()
+    (-keep #'identity '()) => '())
 
   (defexamples -concat
     (-concat '(1)) => '(1)