Add Iterator::collect_into

[frengor]

This PR adds Iterator::collect_into as proposed by @cormacrelf in #48597 (see #48597 (comment)).
Followup of #92982.

This adds the following method to the Iterator trait:

fn collect_into<E: Extend<Self::Item>>(self, collection: &mut E) -> &mut E

[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.

Please see the contribution instructions for more information.

[dtolnay]

I've skimmed the previous discussions in #48597 and #92982 and I don't personally see the appeal of this. Adding a minor variation like this to accomplish something that is already easy distracts people into having to think about which way to write the same thing when, rather than just writing what they mean, and that overshadows any benefit of having the API.

Is there someone else from @rust-lang/libs-api who would prefer to see this signature added?

fn collect_into<E: Extend<Self::Item>>(self, collection: &mut E) -> &mut E

If so, I'll let you approve the unstable and we can hash it out further when it comes to stabilization.

[m-ou-se]

I'm not entirely convinced, but I do see how it makes Extend more discoverable by making collect_into one of the possible options at the end of a iterator method chain. Just like how .collect() is much more discoverable than FromIter, even though Collection::from_iter(..) can often result in less verbose code.

(I don't think collect_into() should return anything though.)

Some relevant grep counts from the crates on crates.io:

collect:   256_874
from_iter:   9_225
extend:     57_110

Extend also has some useful implementations that might be nice to make more discoverable, such as extending a pair of two collections at once ('unzip').

(That particular implementation would be more powerful if we had impl<E: Extend> Extend for &mut E, which is technically a breaking change and was therefore rejected four years ago. However, I'm unable to find any code that would break on crates.io, which makes me wonder if we can still decide to add that implementation.)

[frengor]

Adding a minor variation like this to accomplish something that is already easy distracts people into having to think about which way to write the same thing when, rather than just writing what they mean, and that overshadows any benefit of having the API.

I personally don't think collect_into will distract people from writing what they mean, since this also applies to collect: .collect() lets Collection::from_iter(...) to be called from the iterator as well as .collect_into(...) does with Collection::extend(...).
However, I presume nobody thinks too much about the method to choose between .collect() and Collection::from_iter(...).

Moreover, as pointed out by @m-ou-se, when learning about iterators, collect makes beginners discover FromIterator. However, this does not apply to Extend. I think also Extend should deserve its method.

Finally, I think people will just use the method they prefer. Also note that the proposed doc is clearly stating that collect_into is a convenience method:

This method is a convenience method to call Extend::extend,
but instead of being called on a collection, it's called on an iterator.

[bors]

☔ The latest upstream changes (presumably #93645) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #94103) made this pull request unmergeable. Please resolve the merge conflicts.

[m-ou-se]

Alright, let's try this out as an unstable feature.

Can you open a tracking issue and put its number it in the #[unstable] attribute? Thanks!

[frengor]

Can you open a tracking issue and put its number it in the #[unstable] attribute?

Of course, give me a moment.

[m-ou-se]

@bors r+

[bors]

📌 Commit 63eddb3 has been approved by m-ou-se

[cormacrelf]

Awesome, thanks everyone, especially @frengor, IIRC first contribution and did a great job. 🦀

[frengor]

Awesome, thanks everyone, especially @frengor, IIRC first contribution and did a great job. 🦀

Thank you!