Iterators

Iterators in Rust provide a way to lazily evaluate a sequence of values. All iterators implement the trait, which has one associated type,, and one method, , with the following signature:

Calling  progresses the iterator and returns   with the next value. This is often called consuming the next value. When the iterator is finished, calling  returns.

Iterators are analogous to the  monad in Haskell, and iterators in many other languages like Python.

and loops
is a trait that converts any collection into an iterator over its elements. It is implemented for all collection and collection-like types in the standard library, such as, , and slices. It is also implemented for all iterators as the identity function.

It is most useful in for loops, which can iterate over any type that implements. It first converts the variable into an iterator and then repeatedly calls its  method until it returns   -   is therefore logically equivalent to , but looks cleaner and clearer.

and
The is the opposite of   - it converts an iterator into a collection instead of the other way around. It is primarily not used directly, but rather through the iterator's method.

is implemented for all collection types, such as,  ,   etc, but is also implemented for   and  , where it takes an iterator of  s and  s and 'flattens' it into a single   or.

Example
It can also be used to convert one collection type into another: Flattening s:

In some situations, Rust can produce more efficient code if it knows the number of elements of the iterator up front. For example, when collecting into a, Rust can set the correct capacity to start with and avoid reallocation. The trait provides this, and so iterators that implement this can be collected very efficiently.

Unless you are manually implementing an iterator, you don't generally have to worry about whether  is implemented or not - Rust will automatically implement it wherever it is possible.

Fused iterators
Calling  on an iterator that has already returned   once has unspecified (but not undefined) behavior. It might return,  , or even panic. However, it can be useful to have an iterator that will continue to return  after finishing. The trait guarantees this, and it is implemented by all iterators that have this behavior. Additionally, any iterator can become fused by calling on it, which for already-fused iterators is a no-op and for unfused iterators will keep track of whether the iterator has ended or not.

Double ended iterators
Sometimes it's necessary to iterate over something in reverse direction. Iterators that implement the trait require a   method which consumes an element from the end of the iterator. Double ended iterators also provide a  method, which reverses the iterator. This means that calling  now consumes an element from the end of the iterator, and   consumes an element from the start.

,
Checks if a condition is  for all elements or at least one element of the iterator. This consumes the iterator, or a part of it.

Combines an iterator with another iterator or something that can be converted to an iterator. They are iterated after each other.

,,,  ,  ,  ,  ,  ,
Compares two iterators. The other value doesn't need to be an iterator, if it can be converted to an iterator. These consume the iterators.

Collects the elements into a new collection, using the trait. This consumes the iterator.

,
Converts an iterator over references to an iterator over owned values by dereferencing or cloning them.

Returns the number of elements in the iterator. This consumes the iterator.

,,,  ,  ,  ,  ,
Combines all elements of the iterator with a mathematical operation. This consumes the iterator.

Repeats an iterator endlessly.

Adds a zero-based index to each element of the iterator.

Creates an iterator that contains only the elements from the original iterator that fulfill a certain condition.

Searches for an element that satisfies a predicate. This consumes the iterator or a part of it.

Converts an iterator over iterators (or elements that can be converted to an iterator)

, ,
Combinations of  + ,   +   and   +  , respectively.

An iterator method that applies a function, producing a single, final value. This consumes the iterator.

An alternative to a  loop. This calls a closure on each element of the iterator. This consumes the iterator.

This returns a fused iterator, i.e. an iterator that always returns  after the first.

Calls a closure on each element of the iterator, but doesn't modify it.

Checks if the elements of this iterator are partitioned according to the given predicate, such that all those that return  precede all those that return. This consumes the iterator.

, ,
Checks if the elements of this iterator are sorted. This consumes the iterator.

Returns the last element. This consumes the iterator.

Note that this can be expensive, unless the iterator implements.

Returns a new iterator where each element is mapped to something else.

Returns the n-th element, starting at 0. This consumes n elements of the iterator.

Consumes an iterator, creating two collections from it. The predicate passed to  can return , or. returns a pair, all of the elements for which it returned, and all of the elements for which it returned.

Creates an iterator which can use  to look at the next element of the iterator without consuming it.

,
Searches for an element in an iterator, returning its index. This consumes the iterator or a part of it.

searches from the right. This is only possible if the iterator implements.

Returns an iterator where the order of elements is reversed. This is only possible if the iterator implements.

An iterator adaptor similar to  that holds internal state and produces a new iterator.

,
Creates an iterator that skips the first n elements, or skips elements while a predicate returns. This consumes several elements of the iterator.

Creates an iterator starting at the same point, but stepping by the given amount at each iteration.

,
Creates an iterator that yields its first n elements, or yields elements only until a predicate returns.

, ,
Fallible variants of,  ,

Creates a new iterator where each element of two iterators is combined into a tuple.

Does the opposite of, it converts an iterator of pairs into a pair of collections. This consumes the iterator.