[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/dash 999cae9 253/316: Fix short-circuiting of --first
From: |
ELPA Syncer |
Subject: |
[elpa] externals/dash 999cae9 253/316: Fix short-circuiting of --first |
Date: |
Mon, 15 Feb 2021 15:58:11 -0500 (EST) |
branch: externals/dash
commit 999cae96f0c83b068aefff73afa61fe9e7dfa536
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>
Fix short-circuiting of --first
* dash.el (--first): Stop looping even if needle is nil. Extend
docstring.
(-first): Extend docstring.
* dev/examples.el (-first): Extend tests.
* README.md:
* dash.texi: Regenerate docs.
---
README.md | 14 +++++++-------
dash.el | 18 +++++++++++-------
dash.texi | 18 +++++++++---------
dev/examples.el | 29 ++++++++++++++++++++++++-----
4 files changed, 51 insertions(+), 28 deletions(-)
diff --git a/README.md b/README.md
index ff51a38..d019838 100644
--- a/README.md
+++ b/README.md
@@ -1964,16 +1964,16 @@ See also: [`-flatten-n`](#-flatten-n-num-list),
[`-table`](#-table-fn-rest-lists
#### -first `(pred list)`
-Return the first x in `list` where (`pred` x) is non-nil, else nil.
-
+Return the first item in `list` for which `pred` returns non-nil.
+Return nil if no such element is found.
To get the first item in the list no questions asked, use `car`.
-
-Alias: `-find`
+Alias: `-find`.
+This function's anaphoric counterpart is `--first`.
```el
-(-first 'even? '(1 2 3)) ;; => 2
-(-first 'even? '(1 3 5)) ;; => nil
-(-first 'null '(1 3 5)) ;; => nil
+(-first #'natnump '(-1 0 1)) ;; => 0
+(-first #'null '(1 2 3)) ;; => nil
+(--first (> it 2) '(1 2 3)) ;; => 3
```
#### -some `(pred list)`
diff --git a/dash.el b/dash.el
index 3c51812..c8b652b 100644
--- a/dash.el
+++ b/dash.el
@@ -741,20 +741,24 @@ If ELEMENTS is non nil, append these to the list as well."
(-concat list (list elem) elements))
(defmacro --first (form list)
- "Anaphoric form of `-first'."
+ "Return the first item in LIST for which FORM evals to non-nil.
+Return nil if no such element is found.
+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 `-first'."
(declare (debug (form form)))
(let ((n (make-symbol "needle")))
`(let (,n)
- (--each-while ,list (not ,n)
- (when ,form (setq ,n it)))
+ (--each-while ,list (or (not ,form)
+ (ignore (setq ,n it))))
,n)))
(defun -first (pred list)
- "Return the first x in LIST where (PRED x) is non-nil, else nil.
-
+ "Return the first item in LIST for which PRED returns non-nil.
+Return nil if no such element is found.
To get the first item in the list no questions asked, use `car'.
-
-Alias: `-find'"
+Alias: `-find'.
+This function's anaphoric counterpart is `--first'."
(--first (funcall pred it) list))
(defalias '-find '-first)
diff --git a/dash.texi b/dash.texi
index a98d7df..e998024 100644
--- a/dash.texi
+++ b/dash.texi
@@ -2973,24 +2973,24 @@ See also: @code{-flatten-n} (@pxref{-flatten-n}),
@code{-table} (@pxref{-table})
@anchor{-first}
@defun -first (pred list)
-Return the first x in @var{list} where (@var{pred} x) is non-nil, else nil.
-
+Return the first item in @var{list} for which @var{pred} returns non-nil.
+Return nil if no such element is found.
To get the first item in the list no questions asked, use @code{car}.
-
-Alias: @code{-find}
+Alias: @code{-find}.
+This function's anaphoric counterpart is @code{--first}.
@example
@group
-(-first 'even? '(1 2 3))
- @result{} 2
+(-first #'natnump '(-1 0 1))
+ @result{} 0
@end group
@group
-(-first 'even? '(1 3 5))
+(-first #'null '(1 2 3))
@result{} nil
@end group
@group
-(-first 'null '(1 3 5))
- @result{} nil
+(--first (> it 2) '(1 2 3))
+ @result{} 3
@end group
@end example
@end defun
diff --git a/dev/examples.el b/dev/examples.el
index 30e55c3..18e5668 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -980,11 +980,30 @@ value rather than consuming a list to produce a single
value."
(-flatten-n 2 (apply '-table 'list (-repeat 3 '(1 2)))) => '((1 1 1) (2 1
1) (1 2 1) (2 2 1) (1 1 2) (2 1 2) (1 2 2) (2 2 2)))
(defexamples -first
- (-first 'even? '(1 2 3)) => 2
- (-first 'even? '(1 3 5)) => nil
- (-first 'null '(1 3 5)) => nil
- (-first 'null '(1 3 ())) => nil
- (--first (> it 2) '(1 2 3)) => 3)
+ (-first #'natnump '(-1 0 1)) => 0
+ (-first #'null '(1 2 3)) => nil
+ (--first (> it 2) '(1 2 3)) => 3
+ (let ((c 0)) (--first (setq c (1+ c)) '(nil nil nil)) c) => 1
+ (--first nil '(1 2 3)) => nil
+ (--first nil '(1)) => nil
+ (--first nil '()) => nil
+ (-first #'ignore '(1 2 3)) => nil
+ (-first #'ignore '(1)) => nil
+ (-first #'ignore '()) => nil
+ (--first (not it) '(1 2 nil)) => nil
+ (--first (not it) '(nil 1 2)) => nil
+ (--first (not it) '(nil)) => nil
+ (--first (not it) '()) => nil
+ (-first #'null '(1 2 nil)) => nil
+ (-first #'null '(nil 1 2)) => nil
+ (-first #'null '(nil)) => nil
+ (-first #'null '()) => nil
+ (--first t '(1 2 3)) => 1
+ (--first t '(1)) => 1
+ (--first t '()) => nil
+ (-first #'identity '(1 2 3)) => 1
+ (-first #'identity '(1)) => 1
+ (-first #'identity '()) => nil)
(defexamples -some
(-some 'even? '(1 2 3)) => t
- [elpa] externals/dash 6c41b32 301/316: Move case-fold-search binding to where it's used, (continued)
- [elpa] externals/dash 6c41b32 301/316: Move case-fold-search binding to where it's used, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 1c711f1 303/316: Unquote results in Texinfo examples, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 1bf9ddb 304/316: Makefile aesthetics, ELPA Syncer, 2021/02/15
- [elpa] externals/dash da0415b 312/316: * NEWS.md (2.18): Start news for upcoming release., ELPA Syncer, 2021/02/15
- [elpa] externals/dash 5eea156 315/316: Absorb dash-functional into dash, ELPA Syncer, 2021/02/15
- [elpa] externals/dash eaf33b3 226/316: Add info-lookup-symbol support, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 565055e 229/316: * dash.el (---truthy?): Simplify., ELPA Syncer, 2021/02/15
- [elpa] externals/dash 97bd233 231/316: Use lexical binding for -grade-up/down, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 1152feb 237/316: Deprecate variadic -list, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 609ac28 245/316: Improve Texinfo markup when documenting errors, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 999cae9 253/316: Fix short-circuiting of --first,
ELPA Syncer <=
- [elpa] externals/dash 3726eb1 254/316: Improve the examples of -some, ELPA Syncer, 2021/02/15
- [elpa] externals/dash b0bef0f 276/316: Don't set text-quoting-style globally, ELPA Syncer, 2021/02/15
- [elpa] externals/dash bedc804 282/316: Improve function-to-info, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 9727f7c 288/316: Simplify Lisp -> Texinfo printing, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 7b2584c 294/316: Simplify GitHub link creation, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 7048e68 296/316: Restore some newlines in docstrings, ELPA Syncer, 2021/02/15
- [elpa] externals/dash f6554c3 298/316: Unquote results in README examples, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 39e5b12 306/316: Merge pull request #370 from blc/news, ELPA Syncer, 2021/02/15
- [elpa] externals/dash af21da3 307/316: * dash-functional.el: Fix Author header., ELPA Syncer, 2021/02/15
- [elpa] externals/dash 9c6b979 309/316: Unify dev/examples-to-*.el files, ELPA Syncer, 2021/02/15