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.
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:
mapIndexedandfilterIndexedgive 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 aList<String>, not aList<Any?>. That is the only filter that does so, because the compiler can prove the type.filterNotNull()removesnullelements and turnsList<Any?>intoList<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:
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:
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:
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:
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> |
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:
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.
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:
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,associateByandtoMapkeep only the last value per key. UsegroupByif keys can repeat. - Side effects inside
map.mapis for producing values. If you only want to do something with each element (printing, saving), useforEach; amapwhose result you ignore is almost always a bug. ziptruncation. 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. What does
listOf("1", "x", "3").mapNotNull { it.toIntOrNull() }return?toIntOrNull()returnsnullforx, andmapNotNulldiscards null results, leaving the integers[1, 3]. -
2. Which function turns
[[1, 2], [3]]into[1, 2, 3]?flatten()merges a collection of collections into one list.flatMap { }ismap { }followed byflatten(). -
3. What is the result of
listOf(1, 2, 3).zip(listOf("a", "b"))?zipstops at the shorter collection, so the third element is silently dropped. -
4. Two books share the same genre. What happens with
books.associateBy { it.genre }?associateByoverwrites earlier entries with the same key. UsegroupByto keep all of them. -
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 towindowed(3).
Summary
maptransforms every element,filterkeeps matching ones, and both return new collections; the original never changes.mapNotNullmaps and dropsnullresults in one pass;filterIsInstance<T>()filters by type and narrows the result type.flatMapandflattenturn nested collections into one flat list.zippairs elements by position (stopping at the shorter list),unzipreverses it,zipWithNextpairs neighbours.associate,associateByandassociateWithbuild maps (the last value per key wins);groupBycollects all elements per key;partitionmakes two lists.chunkedslices without overlap,windowedslides with overlap,withIndexadds positions.- Long chains on big data allocate intermediate lists; use sequences when that matters.
Next: Aggregates and Folding
Track your progress
Create a free account to tick off lessons and pick up where you left off on any device.
of Kotlin lessons completed