[elpa] externals/dash 6be4c03 058/439: !first

[Phillip Lord]

branch: externals/dash
commit 6be4c039c833d18503611a04946fabb250da3c15
Author: Magnar Sveen <address@hidden>
Commit: Magnar Sveen <address@hidden>

    !first
---
 README.md   |   13 +++++++++++++
 bang.el     |   24 +++++++++++++++++-------
 examples.el |    5 +++++
 3 files changed, 35 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 0eeae9e..474b220 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@ This is so much a work in progress that you should definitely 
not be using it ye
 * [!keep](#keep-fn-list) `(fn list)`
 * [!concat](#concat-rest-lists) `(&rest lists)`
 * [!mapcat](#mapcat-fn-list) `(fn list)`
+* [!first](#first-fn-list) `(fn list)`
 * [!partial](#partial-fn-rest-args) `(fn &rest args)`
 * [!difference](#difference-list-list2) `(list list2)`
 * [!intersection](#intersection-list-list2) `(list list2)`
@@ -151,6 +152,18 @@ Thus function `fn` should return a collection.
 (!!mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)
 ```
 
+### !first `(fn list)`
+
+Returns the first x in `list` where (`fn` x) is non-nil, else nil.
+
+To get the first item in the list no questions asked, use `car`.
+
+```cl
+(!first 'even? '(1 2 3)) ;; => 2
+(!first 'even? '(1 3 5)) ;; => nil
+(!!first (> it 2) '(1 2 3)) ;; => 3
+```
+
 ### !partial `(fn &rest args)`
 
 Takes a function `fn` and fewer than the normal arguments to `fn`,
diff --git a/bang.el b/bang.el
index 17ed950..63563bb 100644
--- a/bang.el
+++ b/bang.el
@@ -178,18 +178,28 @@ or with `!compare-fn' if that's non-nil."
           (setq lst (cdr lst)))
         lst))))))
 
+(defmacro !!first (form list)
+  "Anaphoric form of `!first'."
+  `(let ((!--list ,list)
+         (!--needle nil))
+     (while (and !--list (not !--needle))
+       (let ((it (car !--list)))
+         (when ,form (setq !--needle it)))
+       (setq !--list (cdr !--list)))
+     !--needle))
+
+(defun !first (fn list)
+  "Returns the first x in LIST where (FN x) is non-nil, else nil.
+
+To get the first item in the list no questions asked, use `car'."
+  (!!first (funcall fn it) list))
+
 (defun !--truthy? (val)
   (not (null val)))
 
 (defmacro !!any? (form list)
   "Anaphoric form of `!any?'."
-  `(let ((!--list ,list)
-         (!--any nil))
-     (while (and !--list (not !--any))
-       (let ((it (car !--list)))
-         (setq !--any ,form))
-       (setq !--list (cdr !--list)))
-     (!--truthy? !--any)))
+  `(!--truthy? (!!first ,form ,list)))
 
 (defun !any? (fn list)
   "Returns t if (FN x) is non-nil for any x in LIST, else nil.
diff --git a/examples.el b/examples.el
index a79d095..7930874 100644
--- a/examples.el
+++ b/examples.el
@@ -56,6 +56,11 @@
   (!mapcat (lambda (item) (list 0 item)) '(1 2 3)) => '(0 1 0 2 0 3)
   (!!mapcat (list 0 it) '(1 2 3)) => '(0 1 0 2 0 3))
 
+(defexamples !first
+  (!first 'even? '(1 2 3)) => 2
+  (!first 'even? '(1 3 5)) => nil
+  (!!first (> it 2) '(1 2 3)) => 3)
+
 (defexamples !partial
   (funcall (!partial '+ 5) 3) => 8
   (funcall (!partial '+ 5 2) 3) => 10)