Module core::iter
[−]
[src]
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 thestruct
itself. 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:
trait Iterator { type Item; fn next(&mut self) -> Option<Self::Item>; }
An iterator has a method, next()
, which when called, returns an
Option
<Item>
. 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.
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 impl
ementing Iterator
for that
struct
. This is why there are so many struct
s 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<usize> { // 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(); let x = counter.next().unwrap(); println!("{}", x); let x = counter.next().unwrap(); println!("{}", x); let x = counter.next().unwrap(); println!("{}", x); let x = counter.next().unwrap(); println!("{}", x); let x = counter.next().unwrap(); println!("{}", x);
This will print 1
through 5
, each on their own line.
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.
for Loops and IntoIterator
Rust's for
loop syntax is actually sugar for iterators. Here's a basic
example of for
:
let values = vec![1, 2, 3, 4, 5]; for x in values { println!("{}", x); }
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:
let values = vec![1, 2, 3, 4, 5]; for x in values { println!("{}", x); }
Rust de-sugars this into:
fn main() { let values = vec![1, 2, 3, 4, 5]; { let result = match values.into_iter() { mut iter => loop { match iter.next() { Some(x) => { println!("{}", x); }, None => break, } }, }; result } }let values = vec![1, 2, 3, 4, 5]; { let result = match values.into_iter() { mut iter => loop { match iter.next() { Some(x) => { println!("{}", x); }, None => break, } }, }; 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
:
impl<I: Iterator> IntoIterator for I
In other words, all Iterator
s implement IntoIterator
, by just
returning themselves. This means two things:
- If you're writing an
Iterator
, you can use it with afor
loop. - If you're creating a collection, implementing
IntoIterator
for it will allow your collection to be used with thefor
loop.
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 collect()
.
For more, see their documentation.
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:
let v = vec![1, 2, 3, 4, 5]; v.iter().map(|x| println!("{}", x));
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 which must be used: iterator adaptors are lazy and
do nothing unless consumed
The idiomatic way to write a map()
for its side effects is to use a
for
loop instead:
let v = vec![1, 2, 3, 4, 5]; for x in &v { println!("{}", x); }
The two most common ways to evaluate an iterator are to use a for
loop
like this, or using the collect()
adapter to produce a new collection.
Infinity
Iterators do not have to be finite. As an example, an open-ended range is an infinite iterator:
fn main() { let numbers = 0..; }let numbers = 0..;
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.
Reexports
use clone::Clone; |
use cmp; |
use cmp::{Ord, PartialOrd, PartialEq, Ordering}; |
use default::Default; |
use marker; |
use mem; |
use num::{Zero, One}; |
use ops::{self, Add, Sub, FnMut, Mul, RangeFrom}; |
use option::Option::{self, Some, None}; |
use marker::Sized; |
use usize; |
Structs
Chain |
An iterator that strings two iterators together. |
Cloned |
An iterator that clones the elements of an underlying iterator. |
Cycle |
An iterator that repeats endlessly. |
Empty |
An iterator that yields nothing. |
Enumerate |
An iterator that yields the current count and the element during iteration. |
Filter |
An iterator that filters the elements of |
FilterMap |
An iterator that uses |
FlatMap |
An iterator that maps each element to an iterator, and yields the elements of the produced iterators. |
Fuse |
An iterator that yields |
Inspect |
An iterator that calls a function with a reference to each element before yielding it. |
Map |
An iterator that maps the values of |
Once |
An iterator that yields an element exactly once. |
Peekable |
An iterator with a |
Repeat |
An iterator that repeats an element endlessly. |
Rev |
An double-ended iterator with the direction inverted. |
Scan |
An iterator to maintain state while iterating another iterator. |
Skip |
An iterator that skips over |
SkipWhile |
An iterator that rejects elements while |
Take |
An iterator that only iterates over the first |
TakeWhile |
An iterator that only accepts elements while |
Zip |
An iterator that iterates two other iterators simultaneously. |
RangeInclusive |
[Deprecated] An iterator over the range [start, stop] |
StepBy |
[Unstable] An adapter for stepping range iterators by a custom amount. |
Enums
ChainState |
Traits
DoubleEndedIterator |
An iterator able to yield elements from both ends. |
ExactSizeIterator |
An iterator that knows its exact length. |
Extend |
Extend a collection with the contents of an iterator. |
FromIterator |
Conversion from an |
IntoIterator |
Conversion into an |
Iterator |
An interface for dealing with iterators. |
Step |
[Unstable] Objects that can be stepped over in both directions. |
Functions
_assert_is_object_safe | |
empty |
Creates an iterator that yields nothing. |
once |
Creates an iterator that yields an element exactly once. |
repeat |
Creates a new iterator that endlessly repeats a single element. |
range_inclusive |
[Deprecated] Returns an iterator over the range [start, stop]. |
select_fold1 |
Select an element from an iterator based on the given projection and "comparison" function. |