API Docs: std::iter

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/iter/

I've recently been doing a lot of work here, but it should be double checked.

[mdinger]

This section being more filled out is really pretty nice. It's still missing the difference between these:

for i in vec { ... }

for i in &vec { ... }
for i in &*vec { ... }

for i in &mut vec { ... }
for i in &mut *vec { ... }

While the first case is covered, the 2nd and 4th aren't. The 3rd and 5th might not be necessary though they might be seen in the wild.

[steveklabnik]

http://doc.rust-lang.org/nightly/std/iter/trait.Extend.html and http://doc.rust-lang.org/nightly/std/iter/trait.FromIterator.html still need work. It'd be nice to expand http://doc.rust-lang.org/nightly/std/iter/fn.empty.html a bit to cover a use-case.

[steveklabnik]

@mdinger that kind of thing really blelongs on Vec's page, I'd imagine, since that's an aspect of Vec and its implementations. They're all technically "covered", the desugaring is the same.

[mdinger]

I didn't know the desugaring was the same. I thought one went to into_iter, one to iter and one to iter_mut because the syntax worked that way. Not because that's what the vec implementation does.

[steveklabnik]

Check out

• https://github.com/rust-lang/rust/blob/master/src/libcollections/vec.rs#L1244
• https://github.com/rust-lang/rust/blob/master/src/libcollections/vec.rs#L1280
• https://github.com/rust-lang/rust/blob/master/src/libcollections/vec.rs#L1290

The into_iter() delegates to each of those three methods, depending. But it's always from into_iter().

[mdinger]

Ah okay. I didn't know it was always through into_iter. What you could do is use vec as an example and say is "Since vec implements these 3 cases of into_iter, we get to use these methods very conveniently. Any container who likewise implements them gets to utilize the same convenient form! All of the collections implement them (I'm not sure if they do but it sounds good)."