From a781f88cdd8fd16313c439432d3795a8332a8131 Mon Sep 17 00:00:00 2001
From: Axel Karjalainen <axel@axka.fi>
Date: Wed, 7 Aug 2024 22:24:51 +0300
Subject: [PATCH] Add note about Result to `find_or_last` and `find_or_first`

See GH-983
---
 src/lib.rs | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 0082aa989..8b037dfaa 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2000,6 +2000,21 @@ pub trait Itertools: Iterator {
     /// assert_eq!(numbers.iter().find_or_last(|&&x| x > 2), Some(&3));
     /// assert_eq!(std::iter::empty::<i32>().find_or_last(|&x| x > 5), None);
     /// ```
+    ///
+    /// An iterator of [`Result`]s can find the first `Ok` or the last `Err`:
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// let input = vec![Err(()), Ok(11), Err(()), Ok(22)];
+    /// assert_eq!(input.into_iter().find_or_last(|result| result.is_ok()), Some(Ok(11)));
+    ///
+    /// let input: Vec<Result<(), i32>> = vec![Err(11), Err(22)];
+    /// assert_eq!(input.into_iter().find_or_last(|result| result.is_ok()), Some(Err(22)));
+    ///
+    /// let input: Vec<Result<(), i32>> = vec![];
+    /// assert_eq!(input.iter().find_or_last(|result| result.is_ok()), None);
+    /// ```
     fn find_or_last<P>(mut self, mut predicate: P) -> Option<Self::Item>
     where
         Self: Sized,
@@ -2028,6 +2043,21 @@ pub trait Itertools: Iterator {
     /// assert_eq!(numbers.iter().find_or_first(|&&x| x > 2), Some(&3));
     /// assert_eq!(std::iter::empty::<i32>().find_or_first(|&x| x > 5), None);
     /// ```
+    ///
+    /// An iterator of [`Result`]s can find the first `Ok` or the first `Err`:
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// let input = vec![Err(()), Ok(11), Err(()), Ok(22)];
+    /// assert_eq!(input.into_iter().find_or_first(|result| result.is_ok()), Some(Ok(11)));
+    ///
+    /// let input: Vec<Result<(), i32>> = vec![Err(11), Err(22)];
+    /// assert_eq!(input.into_iter().find_or_first(|result| result.is_ok()), Some(Err(11)));
+    ///
+    /// let input: Vec<Result<(), i32>> = vec![];
+    /// assert_eq!(input.iter().find_or_first(|result| result.is_ok()), None);
+    /// ```
     fn find_or_first<P>(mut self, mut predicate: P) -> Option<Self::Item>
     where
         Self: Sized,