Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Standard Library Modules

The std::iter module

Reference for Rust std::iter: the Iterator, IntoIterator, FromIterator and Extend traits plus once, repeat, from_fn, successors, zip and other constructors.

std::iter defines the traits behind every for loop and every iterator chain, and a small set of functions that build iterators from scratch. The core trait is Iterator, which needs only a next method returning Option<Item>; the many adapter methods (map, filter, take, ...) come for free. IntoIterator is what for calls, and FromIterator is what collect calls.

The free functions in the module create iterators without a collection: once, repeat, repeat_n, empty, from_fn, successors, repeat_with, once_with and zip. They are lazy, like all iterators, and nothing runs until something consumes them.

Rust
use std::iter;

let powers: Vec<u32> = iter::successors(Some(1u32), |n| n.checked_mul(10)).collect();

Try it

Rust Building iterators from scratch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Implementing Iterator and FromIterator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Item Description
trait Iterator { type Item; fn next(&mut self) -> Option<Self::Item>; } The core trait. About 75 provided methods.
IntoIterator into_iter(self); implemented for collections, &collection, &mut collection and every Iterator.
FromIterator<A> from_iter; what collect::<T>() uses.
Extend<A> extend; appends the items of an iterator to an existing collection.
DoubleEndedIterator Adds next_back, enabling rev, rfind, rposition.
ExactSizeIterator Adds len; promises size_hint is exact.
FusedIterator Marker: once None, always None.
Sum, Product Back iter.sum() and iter.product().
Peekable, Map, Filter, Zip, ... The adapter structs returned by the provided methods.
once(v), once_with(f) One item.
repeat(v), repeat_n(v, n), repeat_with(f) Endless (cloned) or counted repetition. repeat_n is stable since 1.82.
empty() No items.
from_fn(f) Items from a closure returning Option<T>.
successors(first, f) Each item computed from the previous one until None.
zip(a, b) Free-function form of a.into_iter().zip(b).

Usage notes

  • Laziness: adapters do nothing until consumed by collect, sum, for, count and friends. Forgetting to consume gives an "unused" warning.
  • repeat is infinite, so pair it with take, zip or take_while.
  • from_fn stops the first time the closure returns None; if it never does, the iterator is endless.
  • for x in &v / &mut v / v call the three IntoIterator impls: shared references, mutable references and owned items.
  • Implement size_hint when you know bounds; collect uses it to pre-allocate.
  • Iterator::by_ref lets you take part of an iterator and keep using it afterwards.
  • Step (the trait behind a..b) is still unstable, so custom ranges of your own types need a hand-written iterator.
  • Panics: sum and product of integers overflow-panic in debug builds and wrap in release builds.