Java Stream flatMap()

The Stream flatMap() method is used to flatten a Stream of collections to a Stream of objects. The objects are combined from all the collections in the original Stream.

The flatMap() operation has the effect of applying a one-to-many transformation to the elements of the Stream and then flattening the resulting elements into a new Stream.

Stream.flatMap() helps in converting Stream<Collection<T>> to Stream<T>.

flatMap() = Flattening + map()

1. What is Flattening?

In very layman’s terms, flattening is referred to as merging multiple collections/arrays into one. Consider the following example.

In this example, we have an array of 3 arrays. After the flattening effect, we will have one result array with all the items from the 3 arrays.

Before flattening 	: [[1, 2, 3], [4, 5], [6, 7, 8]]

After flattening 	: [1, 2, 3, 4, 5, 6, 7, 8]

In the following example, lines is a stream of lines in the file. Each line consists of multiple words. The words stream is a fattened version of all streams into a single stream – consisting of all the words in all the lines.

Stream<String> lines = Files.lines(path, StandardCharsets.UTF_8);

Stream<String> words = lines.flatMap(line -> Stream.of(line.split(" +")));

2. Stream flatMap() Method

2.1. Method Syntax

The stream flatMap() method has the following syntax.

<R> Stream<R> flatMap(Function<? super T,? extends Stream<? extends R>> mapper)

• R represents the element type of the new stream.
• mapper is a non-interfering, stateless function to apply to each element which produces a stream of new values.
• The method returns a new stream of objects of type R.

Stream interface has three more similar methods which produce IntStream, LongStream and DoubleStream respectively after the flatMap() operation. If the streams created after flatMap() operations return above given types then consider using these functions directly.

IntStream flatMapToInt(Function<? super T,? extends IntStream> mapper)
LongStream flatMapToLong(Function<? super T,? extends LongStream> mapper)
DoubleStream flatMapToDouble(Function<? super T,? extends DoubleStream> mapper)

2.2. Description

• flatMap() is an intermediate operation and return a new Stream.
• It returns a Stream consisting of the results of replacing each element of the given stream with the contents of a mapped stream produced by applying the provided mapping function to each element.
• The mapper function used for transformation in flatMap() is a stateless function and returns only a stream of new values.
• Each mapped Stream is closed after its contents have been placed into new Stream.
• flatMap() operation flattens the stream; opposite to map() operation which does not apply flattening.

3. Stream flatMap() Examples

Example 1: Converting Nested Lists into a Single List

Java 8 example of Stream.flatMap() function to get a single List containing all elements from a list of lists.

This program uses flatMap() operation to convert List<List<Integer>> to List<Integer>.

List<Integer> list1 = Arrays.asList(1,2,3);
List<Integer> list2 = Arrays.asList(4,5,6);
List<Integer> list3 = Arrays.asList(7,8,9);
  
List<List<Integer>> listOfLists = Arrays.asList(list1, list2, list3);
 
List<Integer> listOfAllIntegers = listOfLists.stream()
          .flatMap(x -> x.stream())
          .collect(Collectors.toList());

System.out.println(listOfAllIntegers);

Program output.

[1, 2, 3, 4, 5, 6, 7, 8, 9]

Example 2: Collecting Nested Arrays into a Sinle List

Java 8 example of Stream.flatMap() function to get a single List containing all elements from an array of arrays.

String[][] dataArray = new String[][]{{"a", "b"}, 
		{"c", "d"}, {"e", "f"}, {"g", "h"}};
         
List<String> listOfAllChars = Arrays.stream(dataArray)
              .flatMap(x -> Arrays.stream(x))
              .collect(Collectors.toList());

System.out.println(listOfAllChars);

Program output.

[a, b, c, d, e, f, g, h]

Drop me your questions related to Stream flatMap() method in Java Stream API.

Happy Learning !!

Sourcecode on Github