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.
use std::iter; let powers: Vec<u32> = iter::successors(Some(1u32), |n| n.checked_mul(10)).collect();
Try it
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.
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,countand friends. Forgetting to consume gives an "unused" warning. repeatis infinite, so pair it withtake,ziportake_while.from_fnstops the first time the closure returnsNone; if it never does, the iterator is endless.for x in &v/&mut v/vcall the threeIntoIteratorimpls: shared references, mutable references and owned items.- Implement
size_hintwhen you know bounds;collectuses it to pre-allocate. Iterator::by_reflets you take part of an iterator and keep using it afterwards.Step(the trait behinda..b) is still unstable, so custom ranges of your own types need a hand-written iterator.- Panics:
sumandproductof integers overflow-panic in debug builds and wrap in release builds.
Related
Vec<T>,std::collections,std::ops- Lessons: Iterators, Custom iterators, Iterator patterns