Collection Operations: Grouping

An introduction to the most important functions for grouping: groupBy, partition, groupingBy, fold, reduce, aggregate and their variants.

— — — — — — — — — — — — — — —

THE CURRENT VERSION OF THIS ARTICLE IS PUBLISHED HERE.

— — — — — — — — — — — — — — —

Tags: #FYI++

This article is part of the Kotlin Primer, an opinionated guide to the Kotlin language, which is indented to help facilitate Kotlin adoption inside Java-centric organizations. It was originally written as an organizational learning resource for Etnetera a.s. and I would like to express my sincere gratitude for their support.

It is recommended to read the Introduction before moving on. Check out the Table of Contents for all articles.

groupBy

inline fun <T, K> Iterable<T>.groupBy(
    keySelector: (T) -> K
): Map<K, List<T>>

The groupBy function is the most common function used for grouping. It allows you to group elements of a collection in a map, under keys given by keySelector.

Example

There is also a variant which allows you to transform the value:

Both also have *To variants.

partition

inline fun <T> Iterable<T>.partition(
    predicate: (T) -> Boolean
): Pair<List<T>, List<T>>

The partition method is, in a sense, a simpler version of groupBy, which allows you to split a collection into a pair of collections — one which satisfies a given predicate, and one which doesn’t.

Groupings

groupingBy

inline fun <T, K> Iterable<T>.groupingBy(
    crossinline keySelector: (T) -> K
): Grouping<T, K>

A more general version of groupBy, groupingBy returns an instance of Grouping, which defines its own methods that can be used to implement more general calculations.

eachCount

fun <T, K> Grouping<T, K>.eachCount(): Map<K, Int>

Returns a map with the count of each group, i.e. for each key: K the map contains the number of elements that were grouped under that key.

The eachCount method also has a *To variant.

fold, reduce

inline fun <T, K, R> Grouping<T, K>.fold(
    initialValueSelector: (key: K, element: T) -> R,
    operation: (key: K, accumulator: R, element: T) -> R
): Map<K, R>

inline fun <S, T : S, K> Grouping<T, K>.reduce(
    operation: (key: K, accumulator: S, element: T) -> S
): Map<K, S>

Essentially applies fold/reduce to each group. The meaning of the parameters is as follows:

initialValueSelector — a function that provides an initial value of accumulator for each group. It’s invoked with parameters:

• key: the key of the group
• element: the first element being encountered in that group

operation — a function that is invoked on each element with the following parameters:

• key: the key of the group this element belongs to
• accumulator: the current value of the accumulator of the group
• element: the element from the source being accumulated

Example

There is also a variant of fold where the initial value for fold is the same for each group:

inline fun <T, K, R> Grouping<T, K>.fold(
    initialValue: R,
    operation: (accumulator: R, element: T) -> R
): Map<K, R>

All the above also have *To variants.

Grouping<T, K>.aggregate

inline fun <T, K, R> Grouping<T, K>.aggregate(
    operation: (
        key: K, 
        accumulator: R?, 
        element: T, 
        first: Boolean
    ) -> R
): Map<K, R>

A slightly different version of fold — instead of specifying the initial value with a function, the information is passed directly into the operation via a parameter.

operation — is invoked on each element with the following parameters:

• key: the key of the group this element belongs to
• accumulator: the current value of the accumulator of the group, can be null if it’s the first element encountered in the group
• element: the element from the source being aggregated
• first: indicates whether it’s the first element encountered in the group

The aggregate method also has a *To variant.

Go back to Collection Operations: Aggregations, jump to the Table of Contents, or continue to Sequences: Why We Need Them.