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

let values = ~[1, 2, 3];

// "Syntactical sugar" taking advantage of an iterator
for &x in values.iter() {
    println!("{}", x);
}

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

This for loop syntax can be applied to any iterator over any type.

ByRef	A mutable reference to an iterator
Chain	An iterator which strings two iterators together
Counter	An infinite iterator starting at `start` and advancing by `step` with each iteration
Cycle	An iterator that repeats endlessly
Enumerate	An iterator which yields the current count and the element during iteration
Filter	An iterator which filters the elements of `iter` with `predicate`
FilterMap	An iterator which 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 which maps the values of `iter` with `f`
Peekable	An iterator with a `peek()` that returns an optional reference to the next element.
Range	An iterator over the range [start, stop)
RangeInclusive	An iterator over the range [start, stop]
RangeStep	An iterator over the range [start, stop) by `step`. It handles overflow by stopping.
RangeStepInclusive	An iterator over the range [start, stop] by `step`. It handles overflow by stopping.
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 which skips over `n` elements of `iter`.
SkipWhile	An iterator which rejects elements while `predicate` is true
Take	An iterator which only iterates over the first `n` iterations of `iter`.
TakeWhile	An iterator which only accepts elements while `predicate` is true
Unfold	An iterator which just modifies the contained state throughout iteration.
Zip	An iterator which iterates two other iterators simultaneously

Enums

MinMaxResult

MinMaxResult is an enum returned by min_max. See OrdIterator::min_max for more detail.

Traits

AdditiveIterator	A trait for iterators over elements which can be added together
CloneableIterator	A trait for iterators that are cloneable.
DoubleEndedIterator	A range iterator able to yield elements from both ends
ExactSize	An iterator that knows its exact length
Extendable	A type growable from an `Iterator` implementation
FromIterator	Conversion from 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.
MultiplicativeIterator	A trait for iterators over elements whose elements can be multiplied together.
MutableDoubleEndedIterator	A double-ended iterator yielding mutable references
OrdIterator	A trait for iterators over elements which can be compared to one another. The type of each element must ascribe to the `Ord` trait.
RandomAccessIterator	An object implementing random access indexing by `uint`

Functions

count	Creates a new counter with the specified start/step
range	Return an iterator over the range [start, stop)
range_inclusive	Return an iterator over the range [start, stop]
range_step	Return an iterator over the range [start, stop) by `step`. It handles overflow by stopping.
range_step_inclusive	Return an iterator over the range [start, stop] by `step`. It handles overflow by stopping.

Modules

Module std::iter

The `Iterator` trait

Rust's `for` loop

Iteration protocol and more

Modules

Structs

Enums

Traits

Functions

Keyboard shortcuts

Search tricks