[elpa] externals/dash 6f5888c 251/316: Extend --filter and --remove docs and tests

[ELPA Syncer]

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

    Extend --filter and --remove docs and tests
    
    * dash.el (--filter, -filter, --remove, -remove): Extend docstrings.
    * dev/examples.el (-filter, -remove): Extend tests.
    
    * README.md:
    * dash.texi: Regenerate docs.
---
 README.md       | 20 +++++++++-----------
 dash.el         | 34 ++++++++++++++++++----------------
 dash.texi       | 24 +++++++++++-------------
 dev/examples.el | 32 +++++++++++++++++++++++++++-----
 4 files changed, 65 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md
index 430e737..f7e9266 100644
--- a/README.md
+++ b/README.md
@@ -515,29 +515,27 @@ Functions returning a sublist of the original list.
 
 #### -filter `(pred list)`
 
-Return a new list of the items in `list` for which `pred` returns a non-nil 
value.
-
-Alias: `-select`
-
-See also: [`-keep`](#-keep-fn-list), [`-remove`](#-remove-pred-list).
+Return a new list of the items in `list` for which `pred` returns non-nil.
+Alias: `-select`.
+This function's anaphoric counterpart `--filter`.
+For similar operations, see also [`-keep`](#-keep-fn-list) and 
[`-remove`](#-remove-pred-list).
 
 ```el
 (-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(2 4)
-(-filter 'even? '(1 2 3 4)) ;; => '(2 4)
+(-filter #'natnump '(-2 -1 0 1 2)) ;; => '(0 1 2)
 (--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => '(2 4)
 ```
 
 #### -remove `(pred list)`
 
 Return a new list of the items in `list` for which `pred` returns nil.
-
-Alias: `-reject`
-
-See also: [`-filter`](#-filter-pred-list).
+Alias: `-reject`.
+This function's anaphoric counterpart `--remove`.
+For similar operations, see also [`-keep`](#-keep-fn-list) and 
[`-filter`](#-filter-pred-list).
 
 ```el
 (-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(1 3)
-(-remove 'even? '(1 2 3 4)) ;; => '(1 3)
+(-remove #'natnump '(-2 -1 0 1 2)) ;; => '(-2 -1)
 (--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)
 ```
 
diff --git a/dash.el b/dash.el
index ce1809a..da701ae 100644
--- a/dash.el
+++ b/dash.el
@@ -416,39 +416,41 @@ For other folds, see also `-reductions-r-from' and
     (list (funcall fn))))
 
 (defmacro --filter (form list)
-  "Anaphoric form of `-filter'.
-
-See also: `--remove'."
+  "Return a new list of the items in LIST for which FORM evals to non-nil.
+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 `-filter'.
+For the opposite operation, see also `--remove'."
   (declare (debug (form form)))
   (let ((r (make-symbol "result")))
     `(let (,r)
-       (--each ,list (when ,form (!cons it ,r)))
+       (--each ,list (when ,form (push it ,r)))
        (nreverse ,r))))
 
 (defun -filter (pred list)
-  "Return a new list of the items in LIST for which PRED returns a non-nil 
value.
-
-Alias: `-select'
-
-See also: `-keep', `-remove'."
+  "Return a new list of the items in LIST for which PRED returns non-nil.
+Alias: `-select'.
+This function's anaphoric counterpart `--filter'.
+For similar operations, see also `-keep' and `-remove'."
   (--filter (funcall pred it) list))
 
 (defalias '-select '-filter)
 (defalias '--select '--filter)
 
 (defmacro --remove (form list)
-  "Anaphoric form of `-remove'.
-
-See also `--filter'."
+  "Return a new list of the items in LIST for which FORM evals to nil.
+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 `-remove'.
+For the opposite operation, see also `--filter'."
   (declare (debug (form form)))
   `(--filter (not ,form) ,list))
 
 (defun -remove (pred list)
   "Return a new list of the items in LIST for which PRED returns nil.
-
-Alias: `-reject'
-
-See also: `-filter'."
+Alias: `-reject'.
+This function's anaphoric counterpart `--remove'.
+For similar operations, see also `-keep' and `-filter'."
   (--remove (funcall pred it) list))
 
 (defalias '-reject '-remove)
diff --git a/dash.texi b/dash.texi
index 77ee980..ae9b03d 100644
--- a/dash.texi
+++ b/dash.texi
@@ -482,11 +482,10 @@ Functions returning a sublist of the original list.
 
 @anchor{-filter}
 @defun -filter (pred list)
-Return a new list of the items in @var{list} for which @var{pred} returns a 
non-nil value.
-
-Alias: @code{-select}
-
-See also: @code{-keep} (@pxref{-keep}), @code{-remove} (@pxref{-remove}).
+Return a new list of the items in @var{list} for which @var{pred} returns 
non-nil.
+Alias: @code{-select}.
+This function's anaphoric counterpart @code{--filter}.
+For similar operations, see also @code{-keep} (@pxref{-keep}) and 
@code{-remove} (@pxref{-remove}).
 
 @example
 @group
@@ -494,8 +493,8 @@ See also: @code{-keep} (@pxref{-keep}), @code{-remove} 
(@pxref{-remove}).
     @result{} '(2 4)
 @end group
 @group
-(-filter 'even? '(1 2 3 4))
-    @result{} '(2 4)
+(-filter #'natnump '(-2 -1 0 1 2))
+    @result{} '(0 1 2)
 @end group
 @group
 (--filter (= 0 (% it 2)) '(1 2 3 4))
@@ -507,10 +506,9 @@ See also: @code{-keep} (@pxref{-keep}), @code{-remove} 
(@pxref{-remove}).
 @anchor{-remove}
 @defun -remove (pred list)
 Return a new list of the items in @var{list} for which @var{pred} returns nil.
-
-Alias: @code{-reject}
-
-See also: @code{-filter} (@pxref{-filter}).
+Alias: @code{-reject}.
+This function's anaphoric counterpart @code{--remove}.
+For similar operations, see also @code{-keep} (@pxref{-keep}) and 
@code{-filter} (@pxref{-filter}).
 
 @example
 @group
@@ -518,8 +516,8 @@ See also: @code{-filter} (@pxref{-filter}).
     @result{} '(1 3)
 @end group
 @group
-(-remove 'even? '(1 2 3 4))
-    @result{} '(1 3)
+(-remove #'natnump '(-2 -1 0 1 2))
+    @result{} '(-2 -1)
 @end group
 @group
 (--remove (= 0 (% it 2)) '(1 2 3 4))
diff --git a/dev/examples.el b/dev/examples.el
index 27fd012..c2e6dbf 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -127,15 +127,37 @@ new list."
 
   (defexamples -filter
     (-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(2 4)
-    (-filter 'even? '(1 2 3 4)) => '(2 4)
-    (--filter (= 0 (% it 2)) '(1 2 3 4)) => '(2 4))
+    (-filter #'natnump '(-2 -1 0 1 2)) => '(0 1 2)
+    (--filter (= 0 (% it 2)) '(1 2 3 4)) => '(2 4)
+    (let ((mod 2)) (-filter (lambda (n) (= 0 (% n mod))) '(1 2 3 4))) => '(2 4)
+    (let ((mod 2)) (--filter (= 0 (% it mod)) '(1 2 3 4))) => '(2 4)
+    (let ((l (list 1 2))) (setcar (-filter #'identity l) 0) l) => '(1 2)
+    (let ((l (list 1 2))) (setcar (--filter it l) 0) l) => '(1 2)
+    (-filter #'identity '()) => '()
+    (-filter #'ignore '()) => '()
+    (--filter it '()) => '()
+    (--filter nil '()) => '()
+    (-filter #'identity '(1)) => '(1)
+    (-filter #'ignore '(1)) => '()
+    (--filter it '(1)) => '(1)
+    (--filter nil '(1)) => '())
 
   (defexamples -remove
     (-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(1 3)
-    (-remove 'even? '(1 2 3 4)) => '(1 3)
+    (-remove #'natnump '(-2 -1 0 1 2)) => '(-2 -1)
     (--remove (= 0 (% it 2)) '(1 2 3 4)) => '(1 3)
-    (let ((mod 2)) (-remove (lambda (num) (= 0 (% num mod))) '(1 2 3 4))) => 
'(1 3)
-    (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3))
+    (let ((mod 2)) (-remove (lambda (n) (= 0 (% n mod))) '(1 2 3 4))) => '(1 3)
+    (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3)
+    (let ((l (list 1 2))) (setcar (-remove #'ignore l) 0) l) => '(1 2)
+    (let ((l (list 1 2))) (setcar (--remove nil l) 0) l) => '(1 2)
+    (-remove #'identity '()) => '()
+    (-remove #'ignore '()) => '()
+    (--remove it '()) => '()
+    (--remove nil '()) => '()
+    (-remove #'identity '(1)) => '()
+    (-remove #'ignore '(1)) => '(1)
+    (--remove it '(1)) => '()
+    (--remove nil '(1)) => '(1))
 
   (defexamples -remove-first
     (-remove-first 'even? '(1 3 5 4 7 8 10)) => '(1 3 5 7 8 10)