Module std::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:

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:

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<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:

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 Iterators implement IntoIterator, by just returning themselves. This means two things:

  1. If you're writing an Iterator, you can use it with a for loop.
  2. If you're creating a collection, implementing IntoIterator for it will allow your collection to be used with the for 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:

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.

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 iter with predicate.

FilterMap

An iterator that uses f to both filter and map elements from iter.

FlatMap

An iterator that maps each element to an iterator, and yields the elements of the produced iterators.

Fuse

An iterator that yields None forever after the underlying iterator yields None once.

Inspect

An iterator that calls a function with a reference to each element before yielding it.

Map

An iterator that maps the values of iter with f.

Once

An iterator that yields an element exactly once.

Peekable

An iterator with a peek() that returns an optional reference to the next element.

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 n elements of iter.

SkipWhile

An iterator that rejects elements while predicate is true.

Take

An iterator that only iterates over the first n iterations of iter.

TakeWhile

An iterator that only accepts elements while predicate is true.

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.

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 Iterator.

IntoIterator

Conversion into an Iterator.

Iterator

An interface for dealing with iterators.

Step [Unstable]

Objects that can be stepped over in both directions.

Functions

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].