Skip to content
Tutorials Center
My learning

Topics

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.

Rust
pub trait IntoIterator {
    type Item;
    type IntoIter: Iterator<Item = Self::Item>;
    fn into_iter(self) -> Self::IntoIter;
}

Try it

Rust Owned, shared and mutable iteration

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 IntoIterator

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

Rust
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> implements IntoIterator for Vec<T> (items T), &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 v moves v. If you still need the collection afterwards, write for x in &v. Calling .iter() is equivalent to (&v).into_iter().
  • Arrays by value. Since the 2021 edition [T; N] implements IntoIterator by value, so for x in [1, 2, 3] gives i32, not &i32. Only edition 2018 code resolved array.into_iter() to the reference version.
  • Every iterator is IntoIterator. The blanket impl returns self, which is why you can pass an iterator anywhere an IntoIterator is expected, such as Vec::extend, zip and chain.
  • Accept impl IntoIterator<Item = T> in APIs when a function only needs to loop once. Callers can then pass a Vec, a slice reference, a range or an iterator chain.
  • Option is iterable. Some(x) yields one item and None yields none, which makes flatten and chain(opt) work.
  • The mirror trait is FromIterator, which builds a collection from an iterator (see collect and FromIterator).