fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F>
    where
        F: FnMut(Self::Item) -> U,
        U: Stream,
        Self: Sized,
    {
        assert_stream::<U::Item, _>(FlatMap::new(self, f))
    }
Maps a stream like [`StreamExt::map`] but flattens nested `Stream`s.

[`StreamExt::map`] is very useful, but if it produces a `Stream` instead,
you would have to chain combinators like `.map(f).flatten()` while this
combinator provides ability to write `.flat_map(f)` instead of chaining.

The provided closure which produces inner streams is executed over all elements
of stream as last inner stream is terminated and next stream item is available.

Note that this function consumes the stream passed into it and returns a
wrapped version of it, similar to the existing `flat_map` methods in the
standard library.

# Examples

```
# futures::executor::block_on(async {
use futures::stream::{self, StreamExt};

let stream = stream::iter(1..=3);
let stream = stream.flat_map(|x| stream::iter(vec![x + 3; x]));

assert_eq!(vec![4, 5, 5, 6, 6, 6], stream.collect::<Vec<_>>().await);
# });
```
futures-util/src/stream/stream/mod.rs