# Module std::iter

1.0.0 · source ·
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 the `struct` 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>;
    }

Run

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 over `T`.

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 `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<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);

Run

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

    let values = vec![1, 2, 3, 4, 5];

    for x in values {
        println!("{x}");
    }

Run

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}");
    }

Run

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
    }

Run

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

Run

In other words, all `Iterator`s 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.

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

Run

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);

Run

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:

    let v = vec![1, 2, 3, 4, 5];
    v.iter().map(|x| println!("{x}"));

Run

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 consumed

The 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}");
    }

Run

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:

    let numbers = 0..;

Run

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}");
    }

Run

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.

    let ones = std::iter::repeat(1);
    let least = ones.min().unwrap(); // Oh no! An infinite loop!
    // `ones.min()` causes an infinite loop, so we won't reach this point!
    println!("The smallest number one is {least}.");

Run

## Structs

- ArrayChunks Experimental
  An iterator over `N` elements of the iterator at a time.
- ByRefSized Experimental
  Like `Iterator::by_ref`, but requiring `Sized` so it can forward generics.
- Intersperse Experimental
  An iterator adapter that places a separator between all elements.
- IntersperseWith Experimental
  An iterator adapter that places a separator between all elements.
- MapWindows Experimental
  An iterator over the mapped windows of another iterator.
- Chain
  An iterator that links two iterators together, in a chain.
- Cloned
  An iterator that clones the elements of an underlying iterator.
- Copied
  An iterator that copies 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.
- Flatten
  An iterator that flattens one level of nesting in an iterator of things that can be turned into iterators.
- FromFn
  An iterator where each iteration calls the provided closure `F: FnMut() -> Option<T>`.
- 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`.
- MapWhile
  An iterator that only accepts elements while `predicate` returns `Some(_)`.
- Once
  An iterator that yields an element exactly once.
- OnceWith
  An iterator that yields a single element of type `A` by applying the provided closure `F: FnOnce() -> A`.
- Peekable
  An iterator with a `peek()` that returns an optional reference to the next element.
- Repeat
  An iterator that repeats an element endlessly.
- RepeatWith
  An iterator that repeats elements of type `A` endlessly by applying the provided closure `F: FnMut() -> A`.
- Rev
  A 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` returns `true`.
- StepBy
  An iterator for stepping iterators by a custom amount.
- Successors
  A new iterator where each successive item is computed based on the preceding one.
- Take
  An iterator that only iterates over the first `n` iterations of `iter`.
- TakeWhile
  An iterator that only accepts elements while `predicate` returns `true`.
- Zip
  An iterator that iterates two other iterators simultaneously.

## Traits

- Step Experimental
  Objects that have a notion of successor and predecessor operations.
- TrustedLen Experimental
  An iterator that reports an accurate length using size_hint.
- TrustedStep Experimental
  A type that upholds all invariants of `Step`.
- 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`.
- FusedIterator
  An iterator that always continues to yield `None` when exhausted.
- IntoIterator
  Conversion into an `Iterator`.
- Iterator
  A trait for dealing with iterators.
- Product
  Trait to represent types that can be created by multiplying elements of an iterator.
- Sum
  Trait to represent types that can be created by summing up an iterator.

## Functions

- from_coroutine Experimental
  Creates a new iterator where each iteration calls the provided coroutine.
- empty
  Creates an iterator that yields nothing.
- from_fn
  Creates a new iterator where each iteration calls the provided closure `F: FnMut() -> Option<T>`.
- once
  Creates an iterator that yields an element exactly once.
- once_with
  Creates an iterator that lazily generates a value exactly once by invoking the provided closure.
- repeat
  Creates a new iterator that endlessly repeats a single element.
- repeat_with
  Creates a new iterator that repeats elements of type `A` endlessly by applying the provided closure, the repeater, `F: FnMut() -> A`.
- successors
  Creates a new iterator where each successive item is computed based on the preceding one.
- zip
  Converts the arguments to iterators and zips them.