Diagnostics around implementing mutable iterators should be improved

[mejrs]

Recently I have seen a lot of (new) users struggle with code like this:

pub struct IterMut<'a, T> {
    inner: &'a mut Vec<T>,
    index: usize,
}

impl<'a, T> Iterator for IterMut<'a, T> {
    type Item = &'a mut T;

    fn next(&mut self) -> Option<Self::Item> {
        let item = self.inner.get_mut(self.index);
        self.index += 1;
        item
    }
}

This doesn't compile, of course:

error: lifetime may not live long enough
  --> src/lib.rs:12:9
   |
6  | impl<'a, T> Iterator for IterMut<'a, T> {
   |      -- lifetime `'a` defined here
...
9  |     fn next(&mut self) -> Option<Self::Item> {
   |             - let's call the lifetime of this reference `'1`
...
12 |         item
   |         ^^^^ associated function was supposed to return data with lifetime `'a` 
but it is returning data with lifetime `'1`

This is often seen as a shortcoming of the language, as a pattern that is correct but the compiler doesn't understand - which in this case, is not untrue. But in many impls do involve overlapping mutable references, which would be unsound.

As for improvements, I have some ideas:

• Reassure the user that they really do need that lifetime, and that they didn't put a wrong lifetime somewhere. Say something like "The contract of Iterator::next demands an item with at least the lifetime 'a"
• Explain splitting borrows. In my experience this clicks well, and users are often surprised they don't need to reach for unsafe code. We should explain this in-line or link to the nomicon.
• Explain why the iterator trait has the lifetime requirements that it has ,e.g. "the_iter.collect(); is a thing"

[mejrs]

@rustbot label +A-diagnostics +D-newcomer-roadblock

[yyy33]

Hi, I'm new to rust and I've been stuck with this problem for a while: Iter iterators that do the same thing compile, but IterMut does not.
I don't understand why the mutator interprets &mut self's lifecycle as '1 instead of 'a? The fact that the Iter iterator compiles means that the compiler interprets &mut selfs lifecycle as 'a, so why doesn't it work for IterMut
I found two related threads, but neither mentioned this. Can you elaborate on why it is wrong for IterMut to use this pattern?
The mutable reference lifetime problem of iterators
How does Vec’s iterator return a mutable reference

[yyy33]

And the third omission rule for lifecycle doesn't seem to work here either. The first code compiles fine, but when I don't identify the lifecycle for the Item, the compiler won't allow it.

pub struct Iter<'a, T> {
    inner: &'a Vec<T>,
    index: usize,
}

impl<'a, T> Iterator for Iter<'a, T> {
    type Item = &'a T;

    fn next(&mut self) -> Option<Self::Item> {
        let item = self.inner.get(self.index);
        self.index += 1;
        item
    }
}

pub struct Iter<'a, T> {
    inner: &'a Vec<T>,
    index: usize,
}

impl<'a, T> Iterator for Iter<'a, T> {
    type Item = &T;

    fn next(&mut self) -> Option<Self::Item> {
        let item = self.inner.get(self.index);
        self.index += 1;
        item
    }
}

error[E0637]: `&` without an explicit lifetime name cannot be used here
    --> src/main.rs:1994:17
     |
1994 |     type Item = &T;
     |                 ^ explicit lifetime name needed here

error: lifetime may not live long enough
    --> src/main.rs:1999:9
     |
1993 | impl<'a, T> Iterator for Iter<'a, T> {
     |      -- lifetime `'a` defined here
...
1999 |         item
     |         ^^^^ returning this value requires that `'a` must outlive `'static`

[mejrs]

Can you elaborate on why it is wrong for IterMut to use this pattern?

this is not the place to get help with rust, you should ask this on discord or https://users.rust-lang.org/ instead

[yyy33]

Can you elaborate on why it is wrong for IterMut to use this pattern?

this is not the place to get help with rust, you should ask this on discord or https://users.rust-lang.org/ instead

Ok, thank you