Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 134 ยท Collections

Collection Transformations

Learn Kotlin collection transformations: map, filter, mapNotNull, flatMap, zip, associate, groupBy, partition, chunked and windowed, with runnable examples, pitfalls and performance notes.

Most programs spend their time turning one collection into another: prices into totals, users into names, lines of text into numbers, a flat list into groups. In many languages that means a for loop, a mutable result list and a few lines of bookkeeping. In Kotlin you describe the transformation instead, with one function call that says what you want.

This lesson walks through the transformation functions you will use every day: map and filter first, then flattening, pairing, indexing, grouping, splitting and sliding over data. Every function returns a new collection and leaves the original untouched, which makes them safe to chain. If you have not yet read about lists, sets and maps, start with Collections Overview, and keep Lambdas at hand because every example passes a small lambda.

map and filter: the two workhorses

map applies a function to every element and collects the results. filter keeps only the elements for which a condition is true. The result of map can have a different element type than the input; the result of filter always has the same type.

Kotlin map, filter and friends

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The output is [1, 4, 9, 16, 25, 36], [0:1, 1:2, 2:3, 3:4, 4:5, 5:6], [2, 4, 6], [1, 3, 5], [1, 4], [two, four] and [1, two, 3.0, four]. Notice three details:

  • mapIndexed and filterIndexed give your lambda the position as well as the element. The underscore in { i, _ -> ... } says "I do not use this parameter".
  • filterIsInstance<String>() filters and changes the static type: the result is a List<String>, not a List<Any?>. That is the only filter that does so, because the compiler can prove the type.
  • filterNotNull() removes null elements and turns List<Any?> into List<Any>.

mapNotNull: transform and drop failures in one step

A very common pattern is "convert each element, and skip the ones that cannot be converted". Parsing is the classic case, because toIntOrNull() returns null for text that is not a number. mapNotNull maps and then discards the null results:

Kotlin mapNotNull for parsing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

You see [12, null, 7, null, 40], then [12, 7, 40], then 59. Plain map keeps the nulls (the type is List<Int?>); mapNotNull returns a clean List<Int>. It is equivalent to map { ... }.filterNotNull() but does the work in one pass without building the intermediate list.

Reach for mapNotNull whenever you would otherwise write a map followed by filterNotNull, or a filter followed by a map that repeats the same check. One pass, one list, and the types come out right.

The type of the result follows the lambda

What the lambda returns decides the element type of the new list. If you promise the wrong type, the compiler tells you where the mismatch is:

Kotlin Wrong result type (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The compiler stops with main.kt:3:43: error: return type mismatch: expected 'String', actual 'Int'. and underlines it * 2. The declared type List<String> forces the lambda to return a String, but it * 2 is an Int. Either drop the type annotation and let Kotlin infer List<Int>, or convert inside the lambda with "${it * 2}".

Calling a transformation on a possibly-null list is also an error, because map is not defined on List<Int>?; the compiler says only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type 'List<Int>?'. Use the safe call list?.map { }, or give the list a default with (list ?: emptyList()).map { }. See Null Safety.

flatMap and flatten: lists of lists

Sometimes each element turns into several results. A sentence becomes words, an order becomes line items. map would give you a list of lists; flatMap gives you one flat list:

Kotlin flatMap and flatten

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The first line is [[red, green], [blue], [cyan, magenta, yellow]]: three elements, each a list. The second is [red, green, blue, cyan, magenta, yellow]: six strings. The third is [1, 2, 3]. flatMap { f } means exactly map { f }.flatten(), and the empty inner list simply contributes nothing. Use flatMap for one-to-many conversions, and flatten() when you already hold a collection of collections.

zip, unzip and zipWithNext: working in pairs

zip walks two collections side by side and pairs up the elements at the same position. It stops at the shorter collection, so extra elements are dropped silently:

Kotlin zip and unzip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The output is [(Ada, 1815), (Alan, 1912), (Grace, 1906)], then [Ada/1815, Alan/1912, Grace/1906], [a, b, c], [1, 2, 3], [(1, 2), (2, 3)] and [1, 1]. The year 2000 has no partner and vanishes. unzip is the inverse: it splits a list of pairs into two lists, which you can destructure straight into two variables. zipWithNext pairs each element with its successor, which is exactly what you need for differences, trends and "is this list sorted?" checks.

associate: building maps from lists

Turning a list into a map is another everyday transformation. There are three flavours, and they differ in which side you compute:

Function You supply Result
associate { k to v } both key and value Map<K, V>
associateBy { k } the key; the element is the value Map<K, Element>
associateWith { v } the value; the element is the key Map<Element, V>
Kotlin associate, groupBy and partition

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

You get {Dune=612, Emma=474, Neuromancer=271, Ulysses=730, Hyperion=482}, the keys [D, E, N, U, H] and the values [true, false, false, true, false]. If two elements produce the same key, the later one overwrites the earlier one; that is by design for associate and associateBy, and it is a classic source of silently lost data. When keys may repeat, use groupBy.

groupBy and partition: sorting items into buckets

groupBy { key } returns a Map<Key, List<Element>> with every element in the bucket for its key. The second form, groupBy(keySelector, valueTransform), transforms the elements as it groups them. The output here is {scifi=[Dune, Neuromancer, Hyperion], classic=[Emma, Ulysses]} and {scifi=[612, 271, 482], classic=[474, 730]}. Keys appear in the order they were first seen.

partition is the two-bucket special case. It returns a Pair<List, List> with the matching elements first and the rest second, so you can destructure it as shown: the long books are [Dune, Ulysses, Hyperion] and the short ones [Emma, Neuromancer]. It is better than calling filter and filterNot separately because the predicate runs once per element, and it never loses an element by accident.

chunked and windowed: slicing into pieces

chunked(n) cuts a collection into consecutive pieces of at most n elements, which is perfect for pagination, batching database inserts or laying items out in rows. windowed(size) slides a window along the data, so the pieces overlap:

Kotlin chunked, windowed and withIndex

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The first line is [[Mon, Tue, Wed], [Thu, Fri, Sat], [Sun]]: the last chunk is simply shorter. The second is [MonTueWed, ThuFriSat, Sun]. windowed(3) produces five overlapping windows from [Mon, Tue, Wed] through [Fri, Sat, Sun]; with step = 2 it moves two elements at a time and gives three windows, and partialWindows = true also keeps the short window [Sun] at the end. The moving average of the temperatures is [12.333333333333334, 12.666666666666666, 11.666666666666666, 11.333333333333334]. Both chunked and windowed accept a lambda that runs on each piece, so you do not have to build the lists of lists first.

withIndex() pairs each element with its position as an IndexedValue that has index and value; the last line prints [Mon, Wed, Fri, Sun]. You can also destructure it in a loop: for ((i, d) in days.withIndex()).

Adding, removing and deduplicating

The operators + and - also transform: they return a new collection with an element (or a whole collection) added or removed. distinct removes duplicates while keeping first occurrences, and distinctBy decides equality with a key function.

Kotlin plus, minus and distinct

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The output is [1, 2, 3, 2, 1, 9], [1, 2, 3, 2, 1, 7, 8], [1, 3, 2, 1], [2, 2], [1, 2, 3], [apple, banana] and [1, 2, 3, 2, 1] (a palindrome, so reversing changes nothing). Look closely at a - 2: it removes only the first occurrence of 2, leaving [1, 3, 2, 1]. Subtracting a whole collection works differently: a - listOf(1, 3) removes every element that appears in the second collection, so only the two 2s remain.

Transformations make new collections

Every function above allocates a new list (or map). That is what makes chains safe, but it also means a long chain creates one intermediate collection per step. For a few hundred elements this does not matter. For millions of elements, or when you only need the first few results, switch to sequences, which process one element at a time through the whole chain. This example counts the work both ways:

Kotlin Eager chain versus sequence

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Both versions return [20, 40]. The eager chain performs 15 steps (10 filter calls and 5 map calls) because each stage finishes the whole list before the next starts. The sequence performs only 6 (4 filter calls and 2 map calls) because it stops as soon as take(2) has what it needs.

Pitfalls

  • Large intermediate lists. Chains of five or six steps on huge lists allocate five or six huge lists. Use asSequence() for big data or early exits.
  • Silent key collisions. associate, associateBy and toMap keep only the last value per key. Use groupBy if keys can repeat.
  • Side effects inside map. map is for producing values. If you only want to do something with each element (printing, saving), use forEach; a map whose result you ignore is almost always a bug.
  • zip truncation. Lists of different lengths lose their tail without any warning. Check sizes first if a mismatch would be a bug.
  • Mutable elements. The new list holds the same element objects, not copies. Changing an object you got from a filtered list changes it in the original too.
  • Empty inputs are fine. All these functions return an empty list or map for an empty input, so you rarely need an if (list.isEmpty()) guard.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does listOf("1", "x", "3").mapNotNull { it.toIntOrNull() } return?

    toIntOrNull() returns null for x, and mapNotNull discards null results, leaving the integers [1, 3].
  2. 2. Which function turns [[1, 2], [3]] into [1, 2, 3]?

    flatten() merges a collection of collections into one list. flatMap { } is map { } followed by flatten().
  3. 3. What is the result of listOf(1, 2, 3).zip(listOf("a", "b"))?

    zip stops at the shorter collection, so the third element is silently dropped.
  4. 4. Two books share the same genre. What happens with books.associateBy { it.genre }?

    associateBy overwrites earlier entries with the same key. Use groupBy to keep all of them.
  5. 5. What does (1..7).toList().chunked(3) return?

    chunked(3) cuts the list into consecutive pieces of at most 3 elements; the last piece may be shorter. The overlapping result belongs to windowed(3).

Summary

  • map transforms every element, filter keeps matching ones, and both return new collections; the original never changes.
  • mapNotNull maps and drops null results in one pass; filterIsInstance<T>() filters by type and narrows the result type.
  • flatMap and flatten turn nested collections into one flat list.
  • zip pairs elements by position (stopping at the shorter list), unzip reverses it, zipWithNext pairs neighbours.
  • associate, associateBy and associateWith build maps (the last value per key wins); groupBy collects all elements per key; partition makes two lists.
  • chunked slices without overlap, windowed slides with overlap, withIndex adds positions.
  • Long chains on big data allocate intermediate lists; use sequences when that matters.

Next: Aggregates and Folding