Tracking issue for Iterator::flatten

[Centril]

Tracking issue for #48115, Iterator::flatten and FlatMap.

[leonardo-m]

A flatten could be useful, but I think there are more important/useful functions/iterators to add before a flatten.

[clarfonthey]

@leonardo-m Clearly not important enough for someone to write a PR/RFC before this one, though. ;)

[clarfonthey]

Also I can't list the number of times I've done .flat_map(|x| x), so, I'm glad this was implemented.

One thing that I think should be clarified is that this only flattens one level, i.e. it will not transform [[[1, 2], [3, 4]], [[5, 6], [7, 8]]] into [1, 2, 3, 4, 5, 6, 7, 8] but [[1, 2], [3, 4], [5, 6], [7, 8]].

[Centril]

@leonardo-m I don't think it has to be an either-or proposition - if there are more useful additions, and there certainly are some from Itertools, they should be made irrespective of this one. Someone just has to write the PRs for those =)

Regarding .flatten() specifically, I believe it gives us easier-to-express specialization opportunities than .flat_map() does such as, flattening a vec::IntoIter<Vec<_>> with a single allocation.
Also, it was mentioned explicitly that neither of .flat_map(|x| x) nor .flat_map(identity) were rather nice and that .flatten() was clearer at rust-lang/rfcs#2306 (comment), rust-lang/rfcs#2306 (comment), and rust-lang/rfcs#2306 (review).

@clarcharr hmm, it does say in the docs that:

and you want to remove one level of indirection.

Perhaps that's not clear enough? Can we fix this during stabilization perhaps if it is not?

[clarfonthey]

@Centril I mentioned that having not actually read the docs yet. ;)

I honestly think that including an example would be clearer; there are tools for languages such as JavaScript, for example, which will completely flatten an array regardless of how many levels it has. Although such a thing would be very difficult and/or impossible to do with Rust's type system, I think it'd be best for it to be clear that this is not a "deep" flatten, just a shallow one.

[Centril]

@clarcharr Updated the docs with your example.

[clarfonthey]

Awesome! Thanks