Add remark regarding DoubleEndedIterator

[phimuemue]

While reviewing rust-itertools/itertools@14293bd#diff-2c16d2ada06ad2fd1fc754679646d471, I realized that a DoubleEndedIterator may yield different elements depending on whether it is traversed forwards or backwards. (Not only the order, but possibly also the yielded values.)

I found this remarkable, but could not find anything in the current docs, so I thought it may be worth mentioning this explicitly.

Unfortunately, I could not test these changes locally (rustdoc complains about unresolved import). Sorry if this causes headache.

If I should change something, please let me know. If it seems too trivial, feel free to just close this PR.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @dtolnay (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[dtolnay]

Thanks, that code is a helpful demo of this behavior.

[dtolnay]

@bors r+ rollup

[bors]

📌 Commit b60fe39 has been approved by dtolnay

[ssomers]

I stumbled upon the comment and found it definitely useful but hard to understand, and I'm no longer a noob. The sentence "The elements yielded by DoubleEndedIterator’s methods may differ from the ones yielded by Iterator’s methods" sounds mysterious, and there's no further explanation other than figuring out the code. And that code is in the documentation of method next_back but also illustrates rfold.

I suggest it should be about how backward iteration differs from forward iteration, and belongs at the trait level. Or that it limits itself to next_back and reminds you that Iterator has a last that you can invoke on any DoubleEndedIterator, but it does something distinctly different from next_back.