Understanding flatMap

Have you ever scrolled someone’s code and bumped into this weird method called flatMap, not knowing what it actually does from the context? Or maybe you compared it with method map but didn’t really see much difference? If that is the case then this article is for you.

flatMap is extremly usfull when you try to do proper functional programming. In Java it usually means using Streams and Optionals - concepts introduced in version 8. These two types can be thought of as some kind of wrapper over a type, which adds some extra behaviour - Stream<T> wrapps type T allowing to store any number of elements of type T inside, whereas Optional<T> wrapps some type T to implicitly say that the element of that type may or may not be present inside. Both of them share methods map and flatMap. Before we move on, I want to make sure you understand what the map method is doing. It basically allows you to apply the method to the element inside the wrapper and possibly change it’s type:

Function<String, Long> toLong = Long::parseLong; // function which maps String to Long
Optional<String> someString = Optional.of("12L");
Optional<Long> someLong = someString.map(toLong); //aplying the function to the possible String inside
Stream<String> someStrings = Stream.of("10L", "11L");
Stream<Long> someLongs = someStrings.map(toLong); //applying the function to all Strings inside

After applying the function toLong to our wrappers, their inner types changed to the second type of the toLong signature (the result type).

Let’s examine the function Long::parseLong. If we call it using a string that is not actually a valid long it will throw NumberFormatException. But what if Java designers decide to implement it so it returns Optional<Long> instead of just Long and removed the exception? Our code for Optional part would look like that:

Function<String, Optional<Long>> toLongOpt = Long::parseLongOpt;//method I made up
Optional<String> someString = Optional.of("12L");
Optional<Optional<Long>> someLong = someString.map(toLongOpt); //:<

Wow, that is nasty! When we appliednew method to our wrapper, the inner type was changed from String to Optional<Long> (the result type of toLongOpt which we applied). We don’t really need to have a double Optional because just one is perfectly fine. Now, to get the value we need to extract it twice, not mentioning how it would look like when we want to map it again without unwrapping… To restore it to the single type we would need to write a method like this one:

public static <T> Optional<T> flatten(Optional<Optional<T>> optional) {
    return optional.orElse(Optional.empty());
}

This method will flatten our Optional<Optional<T>> to Optional<T> without changing the inner value. The code will look like this:

Function<String, Optional<Long>> toLongOpt = Long::parseLongOpt;
Optional<String> someString = Optional.of("12L");
Optional<Long> someLong = flatten(someString.map(toLongOpt));

This is exactly what method flatMap is doing. It first applies the function returning another Optional to the inside object (if present) and then flattens the result before returning it, so you don’t have to do it yourself. This is how we can use it:

Function<String, Optional<Long>> toLongOpt = Long::parseLongOpt;
Optional<String> someString = Optional.of("12L");
Optional<Long> someLong = someString.flatMap(toLongOpt);

For Stream, we can use it in the situation when the function we want to map our elements with, returns the Stream. (example signature: Function<String, Stream<Long>>).

That’s it. Just remember that flatMap = map + flatten.

If you want to dive into the topic read about the Functor and Monad concepts and the relationship between them.

Stream[Article]

Understanding flatMap

Add a comment