Rust Reference ยท Iterators
The IntoIterator trait
Reference for the Rust IntoIterator trait: how for loops call into_iter, the difference between owned, shared and mutable iteration, and implementing it for your types.
IntoIterator is the trait that says "this value can be turned into an iterator". Every Iterator is automatically an IntoIterator (it returns itself), and so are the standard collections. The for loop is built on it: for x in expr first calls IntoIterator::into_iter(expr) and then calls next on the result.
The method takes self by value, so what you iterate over decides what you get. A Vec<T> yields owned T values and is consumed; a &Vec<T> yields &T and leaves the vector alone; a &mut Vec<T> yields &mut T. Implementing the trait for your own type, and for references to it, makes it usable in for loops and in any function that accepts impl IntoIterator.
pub trait IntoIterator { type Item; type IntoIter: Iterator<Item = Self::Item>; fn into_iter(self) -> Self::IntoIter; }
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
pub trait IntoIterator { type Item; type IntoIter: Iterator<Item = Self::Item>; fn into_iter(self) -> Self::IntoIter; }
| Name | Description |
|---|---|
Item |
The element type produced by the resulting iterator. |
IntoIter |
The concrete iterator type. Its own Item must equal this trait's Item. |
self |
The value (or reference) being converted. It is moved into the call. |
Returns: an iterator over the value's elements.
Usage notes
- Three impls per collection.
Vec<T>implementsIntoIteratorforVec<T>(itemsT),&Vec<T>(items&T) and&mut Vec<T>(items&mut T).HashMap<K, V>yields(K, V),(&K, &V)and(&K, &mut V)pairs. for x in vmovesv. If you still need the collection afterwards, writefor x in &v. Calling.iter()is equivalent to(&v).into_iter().- Arrays by value. Since the 2021 edition
[T; N]implementsIntoIteratorby value, sofor x in [1, 2, 3]givesi32, not&i32. Only edition 2018 code resolvedarray.into_iter()to the reference version. - Every iterator is
IntoIterator. The blanket impl returnsself, which is why you can pass an iterator anywhere anIntoIteratoris expected, such asVec::extend,zipandchain. - Accept
impl IntoIterator<Item = T>in APIs when a function only needs to loop once. Callers can then pass aVec, a slice reference, a range or an iterator chain. Optionis iterable.Some(x)yields one item andNoneyields none, which makesflattenandchain(opt)work.- The mirror trait is
FromIterator, which builds a collection from an iterator (seecollectandFromIterator).