#iterator #traits

no-std fallible-iterator

Fallible iterator traits

6 releases

0.1.5 Jul 16, 2018
0.1.4 Dec 25, 2017
0.1.3 Sep 22, 2016
0.1.2 Jul 20, 2016
0.1.1 May 20, 2016

#17 in Algorithms

Download history 1307/week @ 2018-07-09 1802/week @ 2018-07-16 1927/week @ 2018-07-23 2129/week @ 2018-07-30 2143/week @ 2018-08-06 2100/week @ 2018-08-13 1924/week @ 2018-08-20 2066/week @ 2018-08-27 2543/week @ 2018-09-03 2740/week @ 2018-09-10 1863/week @ 2018-09-17 1796/week @ 2018-09-24 1617/week @ 2018-10-01

6,203 downloads per month
Used in 75 crates (18 directly)

MIT/Apache

47KB
1.5K SLoC

rust-fallible-iterator

CircleCI

Documentation

"Fallible" iterators for Rust.

Features

If the std or alloc features are enabled, this crate provides implementations for Box, Vec, BTreeMap, and BTreeSet. If the std feature is enabled, this crate additionally provides implementations for HashMap and HashSet.

If the std feature is disabled, this crate does not depend on libstd.


lib.rs:

"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 = 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
}

No runtime deps