<commit_before>[//]: # (title: 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.

## Map

The _mapping_ transformation creates a collection from the results of a function on the elements of another collection.
The basic mapping function is [`map()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map.html).
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 [`mapIndexed()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-indexed.html).  

```kotlin

fun main() {
//sampleStart
    val numbers = setOf(1, 2, 3)
    println(numbers.map { it * 3 })
    println(numbers.mapIndexed { idx, value -> value * idx })
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

If the transformation produces `null` on certain elements, you can filter out the `null`s from the result collection by
calling the [`mapNotNull()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-not-null.html) function
instead of `map()`, or [`mapIndexedNotNull()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-indexed-not-null.html)
instead of `mapIndexed()`.

```kotlin

fun main() {
//sampleStart
    val numbers = setOf(1, 2, 3)
    println(numbers.mapNotNull { if ( it == 2) null else it * 3 })
    println(numbers.mapIndexedNotNull { idx, value -> if (idx == 0) null else value * idx })
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

When transforming maps, you have two options: transform keys leaving values unchanged and vice versa.
To apply a given transformation to keys, use [`mapKeys()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-keys.html);
in turn, [`mapValues()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-values.html) transforms values.
Both functions use the transformations that take a map entry as an argument, so you can operate both its key and value.

```kotlin

fun main() {
//sampleStart
    val numbersMap = mapOf("key1" to 1, "key2" to 2, "key3" to 3, "key11" to 11)
    println(numbersMap.mapKeys { it.key.uppercase() })
    println(numbersMap.mapValues { it.value + it.key.length })
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

## Zip

_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()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/zip.html)
extension function.

When called on a collection or an array with another collection (array) as an argument, `zip()` returns the `List` of 
`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`.

```kotlin

fun main() {
//sampleStart
    val colors = listOf("red", "brown", "grey")
    val animals = listOf("fox", "bear", "wolf")
    println(colors zip animals)

    val twoAnimals = listOf("fox", "bear")
    println(colors.zip(twoAnimals))
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

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.

```kotlin
<commit_msg>chore: zip() transformation function description (#2745)<commit_after>[//]: # (title: 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.

## Map

The _mapping_ transformation creates a collection from the results of a function on the elements of another collection.
The basic mapping function is [`map()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map.html).
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 [`mapIndexed()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-indexed.html).  

```kotlin

fun main() {
//sampleStart
    val numbers = setOf(1, 2, 3)
    println(numbers.map { it * 3 })
    println(numbers.mapIndexed { idx, value -> value * idx })
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

If the transformation produces `null` on certain elements, you can filter out the `null`s from the result collection by
calling the [`mapNotNull()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-not-null.html) function
instead of `map()`, or [`mapIndexedNotNull()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-indexed-not-null.html)
instead of `mapIndexed()`.

```kotlin

fun main() {
//sampleStart
    val numbers = setOf(1, 2, 3)
    println(numbers.mapNotNull { if ( it == 2) null else it * 3 })
    println(numbers.mapIndexedNotNull { idx, value -> if (idx == 0) null else value * idx })
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

When transforming maps, you have two options: transform keys leaving values unchanged and vice versa.
To apply a given transformation to keys, use [`mapKeys()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-keys.html);
in turn, [`mapValues()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/map-values.html) transforms values.
Both functions use the transformations that take a map entry as an argument, so you can operate both its key and value.

```kotlin

fun main() {
//sampleStart
    val numbersMap = mapOf("key1" to 1, "key2" to 2, "key3" to 3, "key11" to 11)
    println(numbersMap.mapKeys { it.key.uppercase() })
    println(numbersMap.mapValues { it.value + it.key.length })
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

## Zip

_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()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/zip.html)
extension function.

When called on a collection or an array with another collection (or array) as an argument, `zip()` returns the `List` of 
`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`.

```kotlin

fun main() {
//sampleStart
    val colors = listOf("red", "brown", "grey")
    val animals = listOf("fox", "bear", "wolf")
    println(colors zip animals)

    val twoAnimals = listOf("fox", "bear")
    println(colors.zip(twoAnimals))
//sampleEnd
}
```
{kotlin-runnable="true" kotlin-min-compiler-version="1.3"}

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.

```kotlin

{'fraction_non_alphanumeric': 0.11421628189550426, 'fraction_numerical': 0.007290400972053463, 'mean_word_length': 4.595513256288239, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5616587', 'n_tokens_mistral': 2526, 'n_tokens_neox': 2327, 'n_words': 908}