vec: fix documentation of vec::each

[artagnon]

5ec3aba (Improve documentation for each, 2012-12-27) incorrectly
documented vec::each by providing examples of old_iter::BaseIter usage
in the context of a vector. Since d2e9912 (vec: remove BaseIter
implementation, 2013-06-21), those examples don't even work anymore.
Correct the examples.

Signed-off-by: Ramkumar Ramachandra [email protected]

[huonw]

Hi @artagnon, thanks for the docs! However, they should probably use the new method of iteration via external iterators (defined in std::iterator), since vec::each will be removed soon(-ish). That, is:

let v = [1,2,3,4,5];
v.iter().advance(|&i| { println(i.to_str()); true })

// ...

let v = [1,2,3];
for v.iter().advance |&i| {
    println(i.to_str());
}

(Note that the temporary v is required because of #3511.)

[artagnon]

I know about .iter().advance; I was just documenting vec::each() in the patch. Anyhow, I pushed out a new version: merge if you're happy with this.

I suspected as much about vec::each(). Are you planning to introduce a trait to get [1,2,3].each to work in the future though? It works with hashmaps (because of the Map trait), and the asymmetry is very displeasing.

[huonw]

Well, the each method on the Map trait is likely to be removed.

There are plans for making for use these iterators (that is the for construction checks for the Iterator trait, and/or a yet-to-be-implemented Iterable trait), so one can write for v.iter() |i| { ... } or even for v |i| { ... } (the exact syntax may change), and even for map.iter() |(key, value)| { ... } (again, possibly without the .iter()).

---

In any case, I made a mistake, you are correct that this PR should use each rather than the new technique; however, it may not be merged, since bors testing time is at a premium at the moment and this function is slated for removal. (If each is looking like it will still exist for 0.7, then this should be merged.)

[artagnon]

Okay, thanks for the explanation. I'm deleting the PR.