Trait first_err::FirstErr

pub trait FirstErr<I, T, E> {
    // Required methods
    fn first_err_or_else<F, O>(self, f: F) -> Result<O, E>
       where F: FnOnce(&mut FirstErrIter<Self, T, E>) -> O;
    fn first_err_or<O>(self, value: O) -> Result<O, E>;
}

This trait provides first_err_or_else() method on all Iterator<Item = Result<T, E>>.

Required Methods

fn first_err_or_else<F, O>(self, f: F) -> Result<O, E>where F: FnOnce(&mut FirstErrIter<Self, T, E>) -> O,

Return the first Err item in current iterator or an Ok value return by f closure. If no error found, this method will consume all items before return.

The iterator argument of closure produce the same sequence but stop from first Err item.

Examples

use first_err::FirstErr;

// Everything is Ok.
let ans = [Ok::<u8, u8>(0), Ok(1), Ok(2)]
    .into_iter()
    .first_err_or_else(|iter| iter.sum::<u8>());
assert_eq!(ans, Ok(3));

// Contains some `Err` values.
let ans = [Ok::<u8, u8>(0), Err(1), Err(2)]
    .into_iter()
    .first_err_or_else(|iter| iter.sum::<u8>());
assert_eq!(ans, Err(1));

Guarantees

Not need to consume inner iterator manually:

let ans = [Ok::<u8, u8>(0), Err(1), Err(2)]
    .into_iter()
    .first_err_or_else(|_iter| {}); // not need to consume `_iter` iterator,
assert_eq!(ans, Err(1));            // and the result still correct.

Outer iterator will be evaluated lazily:

let mut vec = RefCell::new(vec![]);

let mut ans = [Ok::<u8, u8>(0), Ok(1), Err(2), Ok(3)]
    .into_iter()
    .inspect(|res| { vec.borrow_mut().push(*res) })         // push value from outer
    .first_err_or_else(|iter| {
        iter
            .inspect(|n| { vec.borrow_mut().push(Ok(42)) }) // push value from inner
            .sum::<u8>()
    });

assert_eq!(ans, Err(2));
assert_eq!(
    vec.into_inner(),
    vec![Ok(0), Ok(42), Ok(1), Ok(42), Err(2)],
);

Caller can’t leak the inner iterator out from f closure:

let iter = [Ok::<u8, u8>(0), Err(1), Err(2)]
    .into_iter()
    .first_err_or_else(|iter| iter); // compile error: can't leak `iter` out

fn first_err_or<O>(self, value: O) -> Result<O, E>

Return the first Err item in current iterator or an Ok value. If no error found, this method will consume all items before return.

This method is a shorter version of first_err_or_else(|_| value).

Examples

// Everything is Ok.
let ans = [Ok::<u8, u8>(0), Ok(1), Ok(2)]
    .into_iter()
    .first_err_or("foo");
assert_eq!(ans, Ok("foo"));

// Contains some `Err` values.
let ans = [Ok::<u8, u8>(0), Err(1), Err(2)]
    .into_iter()
    .first_err_or("foo");
assert_eq!(ans, Err(1));

Object Safety

This trait is not object safe.

Implementors

impl<I, T, E> FirstErr<I, T, E> for Iwhere I: Iterator<Item = Result<T, E>>,