Trait iterr::ItErr[−][src]

pub trait ItErr: Sized + Iterator {
    type ItemError;
    fn lift_err<Wrap, Over, U, F>(
        self, 
        wrap: Wrap
    ) -> LiftErrIter<Over::IntoIter, Self::ItemError>
    where
        Wrap: FnOnce(LiftTrapErrIter<Self, Self::ItemError>) -> Over,
        Over: IntoIterator<Item = Result<U, F>>,
        Self::ItemError: Into<F>;

    fn lift_fold_err<Wrap, U, F>(self, wrap: Wrap) -> Result<U, F>
    where
        Wrap: FnOnce(LiftTrapErrIter<Self, Self::ItemError>) -> Result<U, F>,
        Self::ItemError: Into<F>;

    fn trap_err(
        self, 
        trap: &mut Trap<Self::ItemError>
    ) -> TrapErrIter<Self, Self::ItemError>;

    fn trap_err_raw(
        self, 
        trap: &mut Result<(), Self::ItemError>
    ) -> TrapErrRawIter<Self, Self::ItemError>;
}

Defines iterator combinators for working with iterators of Results.

Associated Types

The iterator item's error type.

Required Methods

ⓘImportant traits for LiftErrIter<It, LiftErr>

Lifts out just the values wrapped in Ok as an iterator, passing it to wrap, which should return another iterator.

This combinator creates a new inner iterator which yields just the Ok values of the base iterator, and passes it to the callable wrap. This allows the callable to consume the inner iterator without having to account for Err cases. Note that the inner iterator yields None as soon as an Err is encountered in the base iterator.

This callable is expected to return a new iterator whose items are Results. This output iterator is then merged with the Err case from the base iterator.

Example

let elems = vec![Ok(1i32), Ok(2), Err(3i32), Ok(4)]
    .into_iter()
    // This iterator's `Item` type is `Result<i32, i32>`.
    .lift_err(|inner| inner
        // This iterator's Item type is `i32`.
        .map(|x| (x*2) as i64)
        .map(|x| Ok::<i64, i32>(x))
    )
    .collect::<Vec<Result<i64, i32>>>();

// Note that the `Err` case cuts off the inner iterator.
assert_eq!(elems, vec![Ok(2i64), Ok(4), Err(3)]);

Lifts out just the values wrapped in Ok as an iterator, passing it to wrap, which should fold the iterator and return the result.

This combinator creates a new inner iterator which yields just the Ok values of the base iterator, and passes it to the callable wrap. This allows the callable to consume the inner iterator without having to account for Err cases. Note that the inner iterator yields None as soon as an Err is encountered in the base iterator.

This callable is expected to return a single Result. This output is then merged with the Err case from the base iterator.

Example

let sum = vec![Ok(1i32), Ok(2), Err(3i32), Ok(4)]
    .into_iter()
    // This iterator's `Item` type is `Result<i32, i32>`.
    .lift_fold_err(|inner| {
        let v = inner
            // This iterator's Item type is `i32`.
            .map(|x| (x*2) as i64)
            .sum::<i64>();
        Ok(v)
    });

assert_eq!(sum, Err(3));
ⓘImportant traits for TrapErrIter<'a, It, E>

Removes Errs from this iterator by trapping them in trap.

This combinator creates a new iterator which yields just the Ok values of the base iterator. If an Err is encountered, it is written to the given trap, and the iterator terminates.

It is the caller's responsibility to use the trap, whether or not an Err was encountered. If a Trap is dropped without being used in a debug build, a panic will be raised.

Example

let mut trap = <_>::default(); // or: `Trap::new()`
// The trap is "armed" as soon as it is created.

let sum: i32 = vec![Ok(1i32), Ok(2), Err(3u8), Ok(4)]
    .into_iter()
    // This iterator's `Item` type is `Result<i32, u8>`.
    .trap_err(&mut trap)
    // This iterator's `Item` type is `i32`.
    .sum();

// **Note**: You should avoid directly using the result of the iterator
// until *after* you have checked the trap.
assert_eq!(sum, 3);

// Convert the final value and the trap into a `Result<i32, u8>`.
let sum = trap.and_ok(sum);

assert_eq!(sum, Err(3));
ⓘImportant traits for TrapErrRawIter<'a, It, E>

Removes Errs from this iterator by trapping them in trap.

This combinator creates a new iterator which yields just the Ok values of the base iterator. If an Err is encountered, it is written to the given trap, and the iterator terminates.

It is the caller's responsibility to check the trap, whether or not an Err was encountered.

Unlike trap_err, this method uses a simple Result<(), _> as the trap, which may be more convenient in some cases.

Note: the compiler will not issue any warnings if the trap is not checked. Passing a mutable borrow to the trap_err_raw method counts as "using" it. It is recommended that you use the trap_err method where possible to help catch mistakes.

Example

let mut trap = Ok(());
let sum: i32 = vec![Ok(1i32), Ok(2), Err(3u8), Ok(4)]
    .into_iter()
    // This iterator's `Item` type is `Result<i32, u8>`.
    .trap_err_raw(&mut trap)
    // This iterator's `Item` type is `i32`.
    .sum();
    
// **Note**: You should avoid directly using the result of the iterator
// until *after* you have checked the trap.
assert_eq!(sum, 3);

// Convert the final value and the trap into a `Result<i32, u8>`.
let sum = trap.and(Ok(sum));

assert_eq!(sum, Err(3));

Implementors