Crate fallible_iterator

"Fallible" iterators.

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

for line in reader.lines() {
    let line = try!(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) = try!(iter.next()) {
    // work with item
}

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.
Enumerate	An iterator that yields the iteration count as well as the values of the underlying iterator.
Fuse	An iterator that yields Ok(None) forever after the underlying iterator yields Ok(None) once.
Map	An iterator which applies a transform to the elements of the underlying iterator.
Peekable	An iterator which can look at the next element without consuming it.
Rev	An iterator which yields elements of the underlying iterator in reverse order.
Take	An iterator which yeilds a limited number of elements from the underlying iterator.

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.
FromFallibleIterator
IntoFallibleIterator	Conversion into a FallibleIterator.

Functions

convert

Converts an Iterator<Item = Result<T, E>> into a FailingIterator<Item = T, Error = E>.