Collection transformation operations
The Kotlin standard library provides a set of extension functions for collection transformations. These functions build new collections from existing ones based on the transformation rules provided. In this page, we'll give an overview of the available collection transformation functions.
The mapping transformation creates a collection from the results of a function on the elements of another collection. The basic mapping function is
map(). It applies the given lambda function to each subsequent element and returns the list of the lambda results. The order of results is the same as the original order of elements. To apply a transformation that additionally uses the element index as an argument, use
If the transformation produces
null on certain elements, you can filter out the
null s from the result collection by calling the
mapNotNull() function instead of
mapIndexedNotNull() instead of
When transforming maps, you have two options: transform keys leaving values unchanged and vice versa. To apply a given transformation to keys, use
mapKeys(); in turn,
mapValues() transforms values. Both functions use the transformations that take a map entry as an argument, so you can operate both its key and value.
Zipping transformation is building pairs from elements with the same positions in both collections. In the Kotlin standard library, this is done by the
zip() extension function.
When called on a collection or an array with another collection (array) as an argument,
zip() returns the
Pair objects. The elements of the receiver collection are the first elements in these pairs.
If the collections have different sizes, the result of the
zip() is the smaller size; the last elements of the larger collection are not included in the result.
zip() can also be called in the infix form
a zip b.
You can also call
zip() with a transformation function that takes two parameters: the receiver element and the argument element. In this case, the result
List contains the return values of the transformation function called on pairs of the receiver and the argument elements with the same positions.
When you have a
Pair s, you can do the reverse transformation – unzipping – that builds two lists from these pairs:
The first list contains the first elements of each
Pairin the original list.
The second list contains the second elements.
To unzip a list of pairs, call
Association transformations allow building maps from the collection elements and certain values associated with them. In different association types, the elements can be either keys or values in the association map.
The basic association function
associateWith() creates a
Map in which the elements of the original collection are keys, and values are produced from them by the given transformation function. If two elements are equal, only the last one remains in the map.
For building maps with collection elements as values, there is the function
associateBy(). It takes a function that returns a key based on an element's value. If two elements are equal, only the last one remains in the map.
associateBy() can also be called with a value transformation function.
Another way to build maps in which both keys and values are somehow produced from collection elements is the function
associate(). It takes a lambda function that returns a
Pair: the key and the value of the corresponding map entry.
associate() produces short-living
Pair objects which may affect the performance. Thus,
associate() should be used when the performance isn't critical or it's more preferable than other options.
An example of the latter is when a key and the corresponding value are produced from an element together.
Here we call a transform function on an element first, and then build a pair from the properties of that function's result.
If you operate nested collections, you may find the standard library functions that provide flat access to nested collection elements useful.
The first function is
flatten(). You can call it on a collection of collections, for example, a
Set s. The function returns a single
List of all the elements of the nested collections.
Another function –
flatMap() provides a flexible way to process nested collections. It takes a function that maps a collection element to another collection. As a result,
flatMap() returns a single list of its return values on all the elements. So,
flatMap() behaves as a subsequent call of
map() (with a collection as a mapping result) and
joinToString() builds a single
String from the collection elements based on the provided arguments.
joinTo() does the same but appends the result to the given
When called with the default arguments, the functions return the result similar to calling
toString() on the collection: a
String of elements' string representations separated by commas with spaces.
To build a custom string representation, you can specify its parameters in function arguments
postfix. The resulting string will start with the
prefix and end with the
separator will come after each element except the last.
For bigger collections, you may want to specify the
limit – a number of elements that will be included into result. If the collection size exceeds the
limit, all the other elements will be replaced with a single value of the
Finally, to customize the representation of elements themselves, provide the