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,

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

The argument iterator of closure will produce the same values in Ok sequence of current iterator, but will stop when encounter the first Err item.

Examples

use first_err::FirstErr;

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

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

Guarantees

No Need to Manually Consume the Inner Iterator

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

Outer Iterator is Evaluated Lazily

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

let mut result = [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!(result, Err(2));
assert_eq!(
    vec.into_inner(),
    vec![Ok(0), Ok(42), Ok(1), Ok(42), Err(2)],
);

Inner Iterator Can’t be Leaked Outside the 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>

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

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

Examples

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

// Contains some `Err` values.
let result = [Ok::<u8, u8>(0), Err(1), Err(2)]
    .into_iter()
    .first_err_or("foo");
assert_eq!(result, 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>>,