Crate fallible_iterator

“Fallible” iterators.

The iterator APIs in the Rust standard library do not support iteration that can fail in a first class manner. These iterators are typically modeled as iterating over Result<T, E> values; for example, the Lines iterator returns io::Result<String>s. When simply iterating over these types, the value being iterated over must be unwrapped in some way before it can be used:

for line in reader.lines() {
    let line = line?;
    // work with line
}

In addition, many of the additional methods on the Iterator trait will not behave properly in the presence of errors when working with these kinds of iterators. For example, if one wanted to count the number of lines of text in a Reader, this might be a way to go about it:

let count = reader.lines().count();

This will return the proper value when the reader operates successfully, but if it encounters an IO error, the result will either be slightly higher than expected if the error is transient, or it may run forever if the error is returned repeatedly!

In contrast, a fallible iterator is built around the concept that a call to next can fail. The trait has an additional Error associated type in addition to the Item type, and next returns Result<Option<Self::Item>, Self::Error> rather than Option<Self::Item>. Methods like count return Results as well.

This does mean that fallible iterators are incompatible with Rust’s for loop syntax, but while let loops offer a similar level of ergonomics:

while let Some(item) = iter.next()? {
    // work with item
}

Fallible closure arguments

Like Iterator, many FallibleIterator methods take closures as arguments. These use the same signatures as their Iterator counterparts, except that FallibleIterator expects the closures to be fallible: they return Result<T, Self::Error> instead of simply T.

For example, the standard library’s Iterator::filter adapter method filters the underlying iterator according to a predicate provided by the user, whose return type is bool. In FallibleIterator::filter, however, the predicate returns Result<bool, Self::Error>:

let numbers = convert("100\n200\nfern\n400".lines().map(Ok::<&str, Box<Error>>));
let big_numbers = numbers.filter(|n| Ok(u64::from_str(n)? > 100));
assert!(big_numbers.count().is_err());

Structs

• Chain
  An iterator which yields the elements of one iterator followed by another.
• Cloned
  An iterator which clones the elements of the underlying iterator.
• Convert
  A fallible iterator that wraps a normal iterator over Results.
• Cycle
  An iterator which cycles another endlessly.
• Empty
  An iterator that yields nothing.
• Enumerate
  An iterator that yields the iteration count as well as the values of the underlying iterator.
• Filter
  An iterator which uses a fallible predicate to determine which values of the underlying iterator should be yielded.
• FilterMap
  An iterator which both filters and maps the values of the underlying iterator.
• FlatMap
  An iterator which maps each element to another iterator, yielding those iterator’s elements.
• Flatten
  An iterator which flattens an iterator of iterators, yielding those iterators’ elements.
• FromFn
  An iterator using a function to generate new values.
• Fuse
  An iterator that yields Ok(None) forever after the underlying iterator yields Ok(None) once.
• Inspect
  An iterator which passes each element to a closure before returning it.
• IntoFallible
  A fallible iterator that wraps a normal iterator over Results.
• Iterator
  A normal (non-fallible) iterator which wraps a fallible iterator.
• Map
  An iterator which applies a fallible transform to the elements of the underlying iterator.
• MapErr
  An iterator which applies a transform to the errors of the underlying iterator.
• Once
  An iterator that yields something exactly once.
• OnceErr
  An iterator that fails with a predetermined error exactly once.
• Peekable
  An iterator which can look at the next element without consuming it.
• Repeat
  An iterator that endlessly repeats a single element.
• RepeatErr
  An iterator that endlessly repeats a single error.
• Rev
  An iterator which yields elements of the underlying iterator in reverse order.
• Scan
  An iterator which applies a stateful closure.
• Skip
  An iterator which skips initial elements.
• SkipWhile
  An iterator which skips initial elements based on a predicate.
• StepBy
  An iterator which steps through the elements of the underlying iterator by a certain amount.
• Take
  An iterator which yields a limited number of elements from the underlying iterator.
• TakeWhile
  An iterator which yields elements based on a predicate.
• Unwrap
  An iterator that unwraps every element yielded by the underlying FallibleIterator
• Zip
  An iterator that yields pairs of this iterator’s and another iterator’s values.

Traits

• DoubleEndedFallibleIterator
  A fallible iterator able to yield elements from both ends.
• FallibleIterator
  An Iterator-like trait that allows for calculation of items to fail.
• IntoFallibleIterator
  Conversion into a FallibleIterator.
• IteratorExt
  An extnsion-trait with set of useful methods to convert core::iter::Iterator into FallibleIterator

Functions

• convert
  Converts an Iterator<Item = Result<T, E>> into a FallibleIterator<Item = T, Error = E>.
• empty
  Creates an iterator that yields nothing.
• from_fn
  Creates an iterator from a fallible function generating values.
• once
  Creates an iterator that yields an element exactly once.
• once_err
  Creates an iterator that fails with a predetermined error exactly once.
• repeat
  Creates an iterator that endlessly repeats a single element.
• repeat_err
  Creates an iterator that endlessly repeats a single error.