Module std::iter [] [src]

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

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 [Unstable]

An iterator over the range [start, stop]

StepBy [Unstable]

An adapter for stepping range iterators by a custom amount.

Unfold [Deprecated]

An iterator that passes mutable state to a closure and yields the result.

Enums

MinMaxResult [Deprecated]

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 [Deprecated]

An object implementing random access indexing by usize

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 the element elt.

iterate [Deprecated]

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 [Deprecated]