Add note about Result to find_or_last and find_or_first

See GH-983

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,