Add seq-find

This function is similar to `seq-some' but returns the found element.
In the cases where nil can be the found element, a sentinel optional
argument can be provided to avoid ambiguities.

* lisp/emacs-lisp/seq.el (seq-find): New function.
* test/automated/seq-tests.el (test-seq-find): Add tests for `seq-find'.
* doc/lispref/sequences.texi (Sequence Functions): Add documentation for
seq-find.

1 files changed, 13 insertions, 0 deletions

diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el
index 751c18f4aae..4b50a0a9b7b 100644
--- a/lisp/emacs-lisp/seq.el
+++ b/lisp/emacs-lisp/seq.el
@@ -270,6 +270,19 @@ If so, return the non-nil value returned by PRED."
           (throw 'seq--break result))))
     nil))
 
+(cl-defgeneric seq-find (pred seq &optional sentinel)
+  "Return the first element for which (PRED element) is non-nil in SEQ.
+If no element is found, return SENTINEL or nil.
+
+Note that `seq-find' has an ambiguity if the found element is nil
+and if no SENTINEL is specified, as it cannot be known if an
+element was found or not."
+  (catch 'seq--break
+    (seq-doseq (elt seq)
+      (when (funcall pred elt)
+        (throw 'seq--break elt)))
+    sentinel))
+
 (cl-defgeneric seq-count (pred seq)
   "Return the number of elements for which (PRED element) is non-nil in SEQ."
   (let ((count 0))