I have been skimming through the news and the source code of the newest LTE Java 17 version and I have encountered with new Stream method called mapMulti
. The early-access JavaDoc says it is similar to flatMap
.
<R> Stream<R> mapMulti(BiConsumer<? super T,? super Consumer<R>> mapper)
- How to perform one to 0..n mapping using this method?
- How does the new method work and how does it differ from
flatMap
. When is each one preferable? - How many times the
mapper
can be called?
Stream::mapMulti
is a new method that is classified as an intermediate operation.It requires a
BiConsumer<T, Consumer<R>> mapper
of the element about to be processed aConsumer
. The latter makes the method look strange at the first glance because it is different from what we are used to at the other intermediate methods such asmap
,filter
, orpeek
where none of them use any variation of*Consumer
.The purpose of the
Consumer
provided right within the lambda expression by the API itself is to accept any number elements to be available in the subsequent pipeline. Therefore, all the elements, regardless of how many, will be propagated.Explanation using simple snippets
One to some (0..1) mapping (similar to
filter
)Using the
consumer.accept(R r)
for only a few selected items achieves filter-alike pipeline. This might get useful in case of checking the element against a predicate and it's mapping to a different value, which would be otherwise done using a combination offilter
andmap
instead. The followingOne to one mapping (similar to
map
)Working with the previous example, when the condition is omitted and every element is mapped into a new one and accepted using the
consumer
, the method effectively behaves likemap
:One to many mapping (similar to
flatMap
)Here things get interesting because one can call
consumer.accept(R r)
any number of times. Let's say we want to replicate the number representing the String length by itself, i.e.2
becomes2
,2
.4
becomes4
,4
,4
,4
. and0
becomes nothing.Comparison with flatMap
The very idea of this mechanism is that is can be called multiple times (including zero) and its usage of
SpinedBuffer
internally allows to push the elements into a single flattened Stream instance without creating a new one for every group of output elements unlikeflatMap
. The JavaDoc states two use-cases when using this method is preferable overflatMap
:Performance-wise, the new method
mapMulti
is a winner in such cases. Check out the benchmark at the bottom of this answer.Filter-map scenario
Using this method instead of
filter
ormap
separately doesn't make sense due to its verbosity and the fact one intermediate stream is created anyway. The exception might be replacing the.filter(..).map(..)
chain called together, which comes handy in the case such as checking the element type and its casting.As seen above, its variations like
mapMultiToDouble
,mapMultiToInt
andmapMultiToLong
were introduced. This comes along themapMulti
methods within the primitive Streams such asIntStream mapMulti(IntStream.IntMapMultiConsumer mapper)
. Also, three new functional interfaces were introduced. Basically, they are the primitive variations ofBiConsumer<T, Consumer<R>>
, example:Combined real use-case scenario
The real power of this method is in its flexibility of usage and creating only one Stream at a time, which is the major advantage over
flatMap
. The two below snippets represent a flatmapping ofProduct
and itsList<Variation>
into0..n
offers represented by theOffer
class and based on certain conditions (product category and the variation availability).Product
withString name
,int basePrice
,String category
andList<Variation> variations
.Variation
withString name
,int price
andboolean availability
.The use of
mapMulti
is more imperatively inclined compared to the declarative approach of the previous-versions Stream methods combination seen in the latter snippet usingflatMap
,map
, andfilter
. From this perspective, it depends on the use-case whether is easier to use an imperative approach. Recursion is a good example described in the JavaDoc.Benchmark
As promised, I have wrote a bunch of micro-benchmarks from ideas collected from the comments. As long as there is quite a lot of code to publish, I have created a GitHub repository with the implementation details and I am about to share the results only.
Stream::flatMap(Function)
vsStream::mapMulti(BiConsumer)
SourceHere we can see the huge difference and a proof the newer method actually works as described and its usage avoid the overhead of creating a new Stream instance with each processed element.
Stream::filter(Predicate).map(Function)
vsStream::mapMulti(BiConsumer)
SourceUsing chained pipelines (not nested, though) is fine.
Stream::flatMap(Function)
withOptional::stream()
vsStream::mapMulti(BiConsumer)
SourceThis one is very interesting, escpecially in terms of usage (see the source code): we are now able to flatten using
mapMulti(Optional::ifPresent)
and as expected, the new method is a bit faster in this case.