Expand description
Composable external iteration.
If you’ve found yourself with a collection of some kind, and needed to perform an operation on the elements of said collection, you’ll quickly run into ‘iterators’. Iterators are heavily used in idiomatic Rust code, so it’s worth becoming familiar with them.
Before explaining more, let’s talk about how this module is structured:
§Organization
This module is largely organized by type:
- Traits are the core portion: these traits define what kind of iterators exist and what you can do with them. The methods of these traits are worth putting some extra study time into.
- Functions provide some helpful ways to create some basic iterators.
- Structs are often the return types of the various methods on this
module’s traits. You’ll usually want to look at the method that creates
the
struct, rather than thestructitself. For more detail about why, see ‘Implementing Iterator’.
That’s it! Let’s dig into iterators.
§Iterator
The heart and soul of this module is the Iterator trait. The core of
Iterator looks like this:
An iterator has a method, next, which when called, returns an
Option<Item>. Calling next will return Some(Item) as long as there
are elements, and once they’ve all been exhausted, will return None to
indicate that iteration is finished. Individual iterators may choose to
resume iteration, and so calling next again may or may not eventually
start returning Some(Item) again at some point (for example, see TryIter).
Iterator’s full definition includes a number of other methods as well,
but they are default methods, built on top of next, and so you get
them for free.
Iterators are also composable, and it’s common to chain them together to do more complex forms of processing. See the Adapters section below for more details.
§The three forms of iteration
There are three common methods which can create iterators from a collection:
iter(), which iterates over&T.iter_mut(), which iterates over&mut T.into_iter(), which iterates overT.
Various things in the standard library may implement one or more of the three, where appropriate.
§Implementing Iterator
Creating an iterator of your own involves two steps: creating a struct to
hold the iterator’s state, and then implementing Iterator for that struct.
This is why there are so many structs in this module: there is one for
each iterator and iterator adapter.
Let’s make an iterator named Counter which counts from 1 to 5:
// First, the struct:
/// An iterator which counts from one to five
struct Counter {
count: usize,
}
// we want our count to start at one, so let's add a new() method to help.
// This isn't strictly necessary, but is convenient. Note that we start
// `count` at zero, we'll see why in `next()`'s implementation below.
impl Counter {
fn new() -> Counter {
Counter { count: 0 }
}
}
// Then, we implement `Iterator` for our `Counter`:
impl Iterator for Counter {
// we will be counting with usize
type Item = usize;
// next() is the only required method
fn next(&mut self) -> Option<Self::Item> {
// Increment our count. This is why we started at zero.
self.count += 1;
// Check to see if we've finished counting or not.
if self.count < 6 {
Some(self.count)
} else {
None
}
}
}
// And now we can use it!
let mut counter = Counter::new();
assert_eq!(counter.next(), Some(1));
assert_eq!(counter.next(), Some(2));
assert_eq!(counter.next(), Some(3));
assert_eq!(counter.next(), Some(4));
assert_eq!(counter.next(), Some(5));
assert_eq!(counter.next(), None);Calling next this way gets repetitive. Rust has a construct which can
call next on your iterator, until it reaches None. Let’s go over that
next.
Also note that Iterator provides a default implementation of methods such as nth and fold
which call next internally. However, it is also possible to write a custom implementation of
methods like nth and fold if an iterator can compute them more efficiently without calling
next.
§for loops and IntoIterator
Rust’s for loop syntax is actually sugar for iterators. Here’s a basic
example of for:
This will print the numbers one through five, each on their own line. But you’ll notice something here: we never called anything on our vector to produce an iterator. What gives?
There’s a trait in the standard library for converting something into an
iterator: IntoIterator. This trait has one method, into_iter,
which converts the thing implementing IntoIterator into an iterator.
Let’s take a look at that for loop again, and what the compiler converts
it into:
Rust de-sugars this into:
let values = vec![1, 2, 3, 4, 5];
{
let result = match IntoIterator::into_iter(values) {
mut iter => loop {
let next;
match iter.next() {
Some(val) => next = val,
None => break,
};
let x = next;
let () = { println!("{x}"); };
},
};
result
}First, we call into_iter() on the value. Then, we match on the iterator
that returns, calling next over and over until we see a None. At
that point, we break out of the loop, and we’re done iterating.
There’s one more subtle bit here: the standard library contains an
interesting implementation of IntoIterator:
In other words, all Iterators implement IntoIterator, by just
returning themselves. This means two things:
- If you’re writing an
Iterator, you can use it with aforloop. - If you’re creating a collection, implementing
IntoIteratorfor it will allow your collection to be used with theforloop.
§Iterating by reference
Since into_iter() takes self by value, using a for loop to iterate
over a collection consumes that collection. Often, you may want to iterate
over a collection without consuming it. Many collections offer methods that
provide iterators over references, conventionally called iter() and
iter_mut() respectively:
let mut values = vec![41];
for x in values.iter_mut() {
*x += 1;
}
for x in values.iter() {
assert_eq!(*x, 42);
}
assert_eq!(values.len(), 1); // `values` is still owned by this function.If a collection type C provides iter(), it usually also implements
IntoIterator for &C, with an implementation that just calls iter().
Likewise, a collection C that provides iter_mut() generally implements
IntoIterator for &mut C by delegating to iter_mut(). This enables a
convenient shorthand:
let mut values = vec![41];
for x in &mut values { // same as `values.iter_mut()`
*x += 1;
}
for x in &values { // same as `values.iter()`
assert_eq!(*x, 42);
}
assert_eq!(values.len(), 1);While many collections offer iter(), not all offer iter_mut(). For
example, mutating the keys of a HashSet<T> could put the collection
into an inconsistent state if the key hashes change, so this collection
only offers iter().
§Adapters
Functions which take an Iterator and return another Iterator are
often called ‘iterator adapters’, as they’re a form of the ‘adapter
pattern’.
Common iterator adapters include map, take, and filter.
For more, see their documentation.
If an iterator adapter panics, the iterator will be in an unspecified (but memory safe) state. This state is also not guaranteed to stay the same across versions of Rust, so you should avoid relying on the exact values returned by an iterator which panicked.
§Laziness
Iterators (and iterator adapters) are lazy. This means that
just creating an iterator doesn’t do a whole lot. Nothing really happens
until you call next. This is sometimes a source of confusion when
creating an iterator solely for its side effects. For example, the map
method calls a closure on each element it iterates over:
This will not print any values, as we only created an iterator, rather than using it. The compiler will warn us about this kind of behavior:
warning: unused result that must be used: iterators are lazy and
do nothing unless consumedThe idiomatic way to write a map for its side effects is to use a
for loop or call the for_each method:
let v = vec![1, 2, 3, 4, 5];
v.iter().for_each(|x| println!("{x}"));
// or
for x in &v {
println!("{x}");
}Another common way to evaluate an iterator is to use the collect
method to produce a new collection.
§Infinity
Iterators do not have to be finite. As an example, an open-ended range is an infinite iterator:
It is common to use the take iterator adapter to turn an infinite
iterator into a finite one:
let numbers = 0..;
let five_numbers = numbers.take(5);
for number in five_numbers {
println!("{number}");
}This will print the numbers 0 through 4, each on their own line.
Bear in mind that methods on infinite iterators, even those for which a
result can be determined mathematically in finite time, might not terminate.
Specifically, methods such as min, which in the general case require
traversing every element in the iterator, are likely not to return
successfully for any infinite iterators.
Re-exports§
pub use self::adapters::Cloned;pub use self::adapters::Copied;pub use self::adapters::Flatten;pub use self::adapters::MapWhile;pub use self::adapters::StepBy;pub use self::adapters::zip;pub use self::adapters::Chain;pub use self::adapters::Cycle;pub use self::adapters::Enumerate;pub use self::adapters::Filter;pub use self::adapters::FilterMap;pub use self::adapters::FlatMap;pub use self::adapters::Fuse;pub use self::adapters::Inspect;pub use self::adapters::Map;pub use self::adapters::Peekable;pub use self::adapters::Rev;pub use self::adapters::Scan;pub use self::adapters::Skip;pub use self::adapters::SkipWhile;pub use self::adapters::Take;pub use self::adapters::TakeWhile;pub use self::adapters::Zip;pub use self::sources::Empty;pub use self::sources::empty;pub use self::sources::FromFn;pub use self::sources::from_fn;pub use self::sources::Once;pub use self::sources::once;pub use self::sources::OnceWith;pub use self::sources::once_with;pub use self::sources::Repeat;pub use self::sources::repeat;pub use self::sources::RepeatN;pub use self::sources::repeat_n;pub use self::sources::RepeatWith;pub use self::sources::repeat_with;pub use self::sources::Successors;pub use self::sources::successors;pub use self::traits::FusedIterator;pub use self::traits::Iterator;pub use self::traits::DoubleEndedIterator;pub use self::traits::ExactSizeIterator;pub use self::traits::Extend;pub use self::traits::FromIterator;pub use self::traits::IntoIterator;pub use self::traits::Product;pub use self::traits::Sum;pub use self::adapters::ArrayChunks;Experimental pub use self::adapters::ByRefSized;Experimental pub use self::adapters::MapWindows;Experimental pub use self::adapters::SourceIter;Experimental pub use self::adapters::TrustedRandomAccess;Experimental pub use self::adapters::TrustedRandomAccessNoCoerce;Experimental pub use self::adapters::chain;Experimental pub use self::adapters::Intersperse;Experimental pub use self::adapters::IntersperseWith;Experimental pub use self::range::Step;Experimental pub use self::sources::FromCoroutine;Experimental pub use self::sources::from_coroutine;Experimental pub use self::traits::InPlaceIterable;Experimental pub use self::traits::TrustedFused;Experimental pub use self::traits::TrustedLen;Experimental pub use self::traits::TrustedStep;Experimental