Collectors partitioningBy in Java

Introduction

The Java Collectors class has a lot of static utility methods that return various collectors. I have already written about the toMap and groupingBy Collectors in Java 8 and other Collector methods added newly in JDK 9 to 11. In this post, we will learn about the Collectors partitioningBy method. We will also see the differences between the Partitioning Collector and groupingBy Collector.

Partitioning Collector with a Predicate

This is the first (and simplest) of the two Collectors partitioningBy method that exists. This one takes a Predicate and returns a Collector that partitions the elements of the stream as per the passed predicate. Each element will be passed to the predicate. Since a predicate can result in either a true or a false, this Collector groups the elements into two sets and returns the result as a map typed as Map<Boolean, List<T>>.

This map will always have two entries; one for Boolean.TRUE and another for Boolean.FALSE. Those elements for which the predicate returned true will be added as a list against Boolean.TRUE and the rest will be mapped to the key Boolean.FALSE.

Note: There are no guarantees on the type, mutability, serializability, or thread-safety of the Map or the List returned.

Let us look at an example.

List<String> strings = List.of("apple", "orange", "banana", "pear");
Map<Boolean, List<String>> partitionedFruitsByLength = strings.stream()
        .collect(Collectors.partitioningBy(fruit -> fruit.length() > 4));

System.out.println(partitionedFruitsByLength);

There are a list of fruits. We create a stream out of the list and collect them using a Collector returned by Collectors.partitioningBy. We pass the predicate fruit -> fruit.length() > 4 which will return true if the name of the fruit is greater than 4 and false otherwise.

{false=[pear], true=[apple, orange, banana]}

The Partitioned Map always has two entries

The map returned by partitioning will always have mappings for both false and true. If the predicate returned true for all the elements, the mapped value for Boolean.FALSE will be an empty list and vice versa.

Let us change the predicate to return true for fruits if its name is greater than or equal to 4.

partitionedFruitsByLength = strings.stream()
        .collect(Collectors.partitioningBy(fruit -> fruit.length() >= 4));
System.out.println(partitionedFruitsByLength);

This prints, 

{false=[], true=[apple, orange, banana, pear]}

The value for false is an empty list.

Partitioning Collectors with a Predicate and a downstream Collector

Sometimes, we might want to do more than just group the elements as a list. There is an overloaded partitioningBy method that takes a downstream collector in addition to a Predicate.

This method returns a Collector that partitions the elements by the passed predicate. But rather than collecting them as a list, it reduces them according to the passed downstream collector. Still it returns a Map with two boolean keys, but the value of the entry in the map is determined by the downstream collector (which does the downstream reduction).

Example: Let us use the same predicate as earlier but count the number of fruits falling in each category. We use a downstream collector of Collectors.counting() for this.

Map<Boolean, Long> fruitsCount = strings.stream()
        .collect(Collectors.partitioningBy(fruit -> fruit.length() > 4,
                Collectors.counting()));
System.out.println(fruitsCount); //{false=1, true=3}

We can see that the value for the key false is 1 as there was one fruit for which the predicate evaluated to false. And the value for the key true is 3.

If we had used a downstream collector of toList(), then it would be equivalent to the first partitioningBy method we saw.

partitionedFruitsByLength = strings.stream()
        .collect(Collectors.partitioningBy(fruit -> fruit.length() > 4,
                Collectors.toList()));

System.out.println(partitionedFruitsByLength); //{false=[pear], true=[apple, orange, banana]}

Partition with a mapping Collector

Let us partition again in the same way but transform the fruit names into upper case before collecting them into the list. We can do this using the mapping collector as the downstream collector. And toList is the downstream collector of the mapping collector.

Map<Boolean, List<String>> partitionedFruitsInUpperCaseByLength = strings.stream()
        .collect(Collectors.partitioningBy(fruit -> fruit.length() > 4,
                Collectors.mapping(String::toUpperCase, Collectors.toList())));

System.out.println(partitionedFruitsInUpperCaseByLength);

String::toUpperCase is a method reference of the lambda expression fruit -> fruit.toUpperCase(). This outputs,

{false=[PEAR], true=[APPLE, ORANGE, BANANA]}

Similarities between Collectors partitioningBy and groupingBy

Let us now look at the similarities between partitioningBy and groupingBy Collectors. There are three overloaded groupingBy methods.

//Group by length
Map<Boolean, List<String>> groupedByLength = strings.stream()
        .collect(Collectors.groupingBy(fruit -> fruit.length() > 4));
System.out.println(groupedByLength); //{false=[pear], true=[apple, orange, banana]}

Map<Boolean, Long> fruitsCount = strings.stream()
        .collect(Collectors.groupingBy(fruit -> fruit.length() > 4,
                Collectors.counting()));
System.out.println(fruitsCount); //{false=1, true=3}

Differences between Collectors partitioningBy and groupingBy

Let us now look at the differences between partitioningBy and groupingBy Collectors. 

Difference in the result keys

The first difference is in the nature of the returned map. As we saw, the partitioningBy will always return a map with exactly two entries; true and false. If no elements are grouped under a key, it would have an empty list.

partitionedFruitsByLength = strings.stream()
        .collect(Collectors.partitioningBy(fruit -> fruit.length() > 3));
System.out.println(partitionedFruitsByLength); //{false=[], true=[apple, orange, banana, pear]

groupedByLength = strings.stream()
        .collect(Collectors.groupingBy(fruit -> fruit.length() > 3));
System.out.println(groupedByLength); //{true=[apple, orange, banana, pear]}

Predicate vs Function

The second difference is related to the lambda’s type (and must be obvious). We have seen that we can use the same lambda expression in different contexts so they get different target type. But if the lambda is defined with a particular target type at compile time we cannot exchange it.

Predicate<String> stringPredicate = str -> str.length() > 4;
Function<String, Boolean> function = str -> str.length() > 4;

//change 1st argument and they won't compile (obviously)
strings.stream()
        .collect(Collectors.partitioningBy(stringPredicate));
strings.stream()
        .collect(Collectors.groupingBy(function));

If we have a Predicate<T>, we can pass it to partitioningBy only and we can pass a Function<T, Boolean> only to a groupingBy and not the other way around.

Conclusion

In this post, we saw about the Collectors partitioningBy method. We learnt that it groups elements by a predicate and can accept a downstream collector for further reduction. Next, we saw the similarities and functional differences between partitioningBy and groupingBy collectors.
Check out the other posts on Java Streams.

Reference links

• Javadoc partitioningBy
• ConcretePage – Partitioningby
• Stackoverflow – Partitioningby
• Javabrahman Partitioningby
• What is meant by lambda target type and target type context in Java?