Crate fallible_iterator
source ·Expand description
“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 Read
er, 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
Result
s 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§
- An iterator which yields the elements of one iterator followed by another.
- An iterator which clones the elements of the underlying iterator.
- A fallible iterator that wraps a normal iterator over
Result
s. - An iterator which cycles another endlessly.
- An iterator that yields the iteration count as well as the values of the underlying iterator.
- An iterator which uses a fallible predicate to determine which values of the underlying iterator should be yielded.
- An iterator which both filters and maps the values of the underlying iterator.
- An iterator which maps each element to another iterator, yielding those iterator’s elements.
- An iterator which flattens an iterator of iterators, yielding those iterators’ elements.
- An iterator that yields
Ok(None)
forever after the underlying iterator yieldsOk(None)
once. - An iterator which passes each element to a closure before returning it.
- A normal (non-fallible) iterator which wraps a fallible iterator.
- An iterator which applies a fallible transform to the elements of the underlying iterator.
- An iterator which applies a transform to the errors of the underlying iterator.
- An iterator which can look at the next element without consuming it.
- An iterator which yields elements of the underlying iterator in reverse order.
- An iterator which applies a stateful closure.
- An iterator which skips initial elements.
- An iterator which skips initial elements based on a predicate.
- An iterator which steps through the elements of the underlying iterator by a certain amount.
- An iterator which yields a limited number of elements from the underlying iterator.
- An iterator which yields elements based on a predicate.
- An iterator that yields pairs of this iterator’s and another iterator’s values.
Traits§
- A fallible iterator able to yield elements from both ends.
- An
Iterator
-like trait that allows for calculation of items to fail. - Conversion from a fallible iterator.
- Conversion into a
FallibleIterator
.
Functions§
- Converts an
Iterator<Item = Result<T, E>>
into aFallibleIterator<Item = T, Error = E>
.