Clarify `Book::for_each_mut`'s note on iterator invalidation

[Ethiraric]

Question

The documentation for Book::for_each_mut states:

Unlike the iter() method, this requires a closure instead of returning an iterator. This is because using iterators can possibly allow you to have iterator invalidation errors.

This hints that for_each_mut should be preferred over iter. mdBook's mdbook mentions in the for developers section the for_each_mut method but leaves out iter as well.

I am not sure I follow under which circumstances there could be invalidation in the iterators.

Can someone explain how and maybe clarify the documentation or give an example?

Version

latest