What is the difference between iter and into_iter?

by

TL;DR:

  • The iterator returned by into_iter may yield any of T, &T or &mut T, depending on the context.
  • The iterator returned by iter will yield &T, by convention.
  • The iterator returned by iter_mut will yield &mut T, by convention.

The first question is: “What is into_iter?”

into_iter comes from the IntoIterator trait:

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

You implement this trait when you want to specify how a particular type is to be converted into an iterator. Most notably, if a type implements IntoIterator it can be used in a for loop.

For example, Vec implements IntoIterator… thrice!

impl<T> IntoIterator for Vec<T>
impl<'a, T> IntoIterator for &'a Vec<T>
impl<'a, T> IntoIterator for &'a mut Vec<T>

Each variant is slightly different.

This one consumes the Vec and its iterator yields values (T directly):

impl<T> IntoIterator for Vec<T> {
    type Item = T;
    type IntoIter = IntoIter<T>;

    fn into_iter(mut self) -> IntoIter<T> { /* ... */ }
}

The other two take the vector by reference (don’t be fooled by the signature of into_iter(self) because self is a reference in both cases) and their iterators will produce references to the elements inside Vec.

This one yields immutable references:

impl<'a, T> IntoIterator for &'a Vec<T> {
    type Item = &'a T;
    type IntoIter = slice::Iter<'a, T>;

    fn into_iter(self) -> slice::Iter<'a, T> { /* ... */ }
}

While this one yields mutable references:

impl<'a, T> IntoIterator for &'a mut Vec<T> {
    type Item = &'a mut T;
    type IntoIter = slice::IterMut<'a, T>;

    fn into_iter(self) -> slice::IterMut<'a, T> { /* ... */ }
}

So:

What is the difference between iter and into_iter?

into_iter is a generic method to obtain an iterator, whether this iterator yields values, immutable references or mutable references is context dependent and can sometimes be surprising.

iter and iter_mut are ad-hoc methods. Their return type is therefore independent of the context, and will conventionally be iterators yielding immutable references and mutable references, respectively.

The author of the Rust by Example post illustrates the surprise coming from the dependence on the context (i.e., the type) on which into_iter is called, and is also compounding the problem by using the fact that:

  1. IntoIterator is not implemented for [T; N], only for &[T; N] and &mut [T; N] — it will be for Rust 2021.
  2. When a method is not implemented for a value, it is automatically searched for references to that value instead

which is very surprising for into_iter since all types (except [T; N]) implement it for all 3 variations (value and references).

Arrays implement IntoIterator (in such a surprising fashion) to make it possible to iterate over references to them in for loops.

As of Rust 1.51, it’s possible for the array to implement an iterator that yields values (via array::IntoIter), but the existing implementation of IntoIterator that automatically references makes it hard to implement by-value iteration via IntoIterator.

More Related Contents:

  1. The compiler suggests I add a ‘static lifetime because the parameter type may not live long enough, but I don’t think that’s what I want
  2. How do I pass disjoint slices from a vector to different threads?
  3. Why does Iterator::take_while take ownership of the iterator?
  4. When should I implement std::convert::From vs std::convert::Into?
  5. Compare enums only by variant, not value
  6. How can I call a mutating method while holding a reference to self?
  7. How do you actually use dynamically sized types in Rust?
  8. “parameter `’a` is never used” error when ‘a is used in type parameter bound
  9. Borrowing references to attributes in a struct
  10. Is it possible to implement methods on type aliases?
  11. How to operate on 2 mutable slices of a Rust array?
  12. Mutating one field while iterating over another immutable field
  13. How can I use a module from outside the src folder in a binary project, such as for integration tests or benchmarks?
  14. How to match on data type in Rust?
  15. Why does Rust allow mutation through a reference field using an immutable binding?
  16. How can I modify self in a closure called from a member function?
  17. Multiple return types from a method
  18. How do I move out of a struct field that is an Option?
  19. Why does this mutable borrow live beyond its scope?
  20. What is unwrap in Rust, and what is it used for?
  21. How can I find a subsequence in a &[u8] slice?
  22. Why “explicit lifetime bound required” for Box in struct?
  23. What is the difference between `|_| async move {}` and `async move |_| {}`
  24. Cannot use moved BufReader after for loop with bufreader.lines()
  25. Expected closure, found a different closure
  26. How can I iterate on an Option?
  27. How does the Rust compiler know `Cell` has internal mutability?
  28. Creating Diesel.rs queries with a dynamic number of .and()’s
  29. How do I match based on a dynamic variable?
  30. How to match trait implementors

Leave a Comment