Module core::iter

Composable external iterators

The Iterator trait

This module defines Rust's core iteration trait. The Iterator trait has one unimplemented method, next. All other methods are derived through default methods to perform operations such as zip, chain, enumerate, and fold.

The goal of this module is to unify iteration across all containers in Rust. An iterator can be considered as a state machine which is used to track which element will be yielded next.

There are various extensions also defined in this module to assist with various types of iteration, such as the DoubleEndedIterator for iterating in reverse, the FromIterator trait for creating a container from an iterator, and much more.

Rust's for loop

The special syntax used by rust's for loop is based around the IntoIterator trait defined in this module. for loops can be viewed as a syntactical expansion into a loop, for example, the for loop in this example is essentially translated to the loop below.

fn main() { let values = vec![1, 2, 3]; for x in values { println!("{}", x); } // Rough translation of the iteration without a `for` iterator. let values = vec![1, 2, 3]; let mut it = values.into_iter(); loop { match it.next() { Some(x) => println!("{}", x), None => break, } } }

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

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

// Rough translation of the iteration without a `for` iterator.
let mut it = values.into_iter();
loop {
    match it.next() {
        Some(x) => println!("{}", x),
        None => break,
    }
}

Because Iterators implement IntoIterator, this for loop syntax can be applied to any iterator over any type.

Modules

order

[Unstable] Functions for lexicographical ordering of sequences.

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
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
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	[Unstable] An iterator over the range [start, stop]
StepBy	[Unstable] An adapter for stepping range iterators by a custom amount.
Unfold	[Unstable] An iterator that passes mutable state to a closure and yields the result.

Enums

MinMaxResult

[Unstable] MinMaxResult is an enum returned by min_max. See Iterator::min_max for more detail.

Traits

DoubleEndedIterator	A range iterator able to yield elements from both ends
ExactSizeIterator	An iterator that knows its exact length
Extend	A type growable from an Iterator implementation
FromIterator	Conversion from an Iterator
IntoIterator	Conversion into an Iterator
Iterator	An interface for dealing with "external iterators". These types of iterators can be resumed at any time as all state is stored internally as opposed to being located on the call stack.
RandomAccessIterator	[Unstable] An object implementing random access indexing by usize
Step	[Unstable] Objects that can be stepped over in both directions.

Functions

repeat	Creates a new iterator that endlessly repeats the element elt.
iterate	[Unstable] Creates a new iterator that produces an infinite sequence of repeated applications of the given function f.
range_inclusive	[Unstable] Returns an iterator over the range [start, stop].

Type Definitions

Iterate

[Unstable] An iterator that repeatedly applies a given function, starting from a given seed value.