Deprecate flatten

[clarfonthey]

This is slated to be added to libstd via rust-lang/rust#48213 and it may be useful to just deprecate this method on itertools now to help push people into adopting it. In the meantime, I think that suggesting .flat_map(|x| x) is a reasonable alternative, even if it's not the most performant.

[bluss]

Ok it's on the list in #223. This time it's for real, we have a real collision and it needs a solution. “Fortunately” it only breaks .flatten() users and not all itertools users. Deprecate sounds good, but to resolve the conflict smoothly, perhaps even a version check and conditional compilation is something we need to use.

[clarfonthey]

Perhaps having the ability to do #[cfg(feature = "iter_flatten")] for the compiler feature might be useful.

[samueltardieu]

@bluss It breaks .flatten() users but also transitively users of libraries using .flatten(). I noticed it indirectly for my pathfinding crate through the recompilation of a program that uses this crate.

[qmx]

.flatten() just hit rustc-stable (1.29), it'd be nice to fix the conflict sooner than later :)