Collections

Read-Only vs Mutable Collections

Kotlin separates read-only and mutable collections at the type level. A List<T> provides only read operations (get, size, contains). A MutableList<T> adds write operations (add, remove, set). This is a design decision, not a technical limitation: the underlying JVM collection is the same, but the Kotlin compiler restricts what you can do through the read-only interface.

val readOnlyList = listOf(1, 2, 3)
// readOnlyList.add(4)  // Compile error

val mutableList = mutableListOf(1, 2, 3)
mutableList.add(4)      // Allowed

This distinction matters because it documents intent. If a function receives List<T>, the caller knows the function will not modify it. If it receives MutableList<T>, modification is expected.

List

Lists are ordered collections that allow duplicates. Use listOf for immutable lists and mutableListOf for mutable ones:

val fruits = listOf("apple", "banana", "cherry")
println(fruits[0])        // apple
println(fruits.size)       // 3
println(fruits.contains("banana"))  // true

// Indexed access with null safety
val second: String? = fruits.getOrNull(1)  // banana
val tenth: String? = fruits.getOrNull(9)   // null

Use listOfNotNull to create a list that filters out nulls:

val mixed = listOfNotNull(1, null, 2, null, 3)
println(mixed)  // [1, 2, 3]

Set

Sets are unordered collections that reject duplicates. Use setOf and mutableSetOf:

val uniqueNumbers = setOf(1, 2, 2, 3, 3, 3)
println(uniqueNumbers)  // [1, 2, 3]
println(uniqueNumbers.size)  // 3

val mutableSet = mutableSetOf("a", "b")
mutableSet.add("c")
mutableSet.add("a")  // Duplicate ignored
println(mutableSet)  // [a, b, c]

Map

Maps store key-value pairs. Keys must be unique; values can repeat:

val capitals = mapOf(
    "USA" to "Washington",
    "Japan" to "Tokyo",
    "Germany" to "Berlin"
)

println(capitals["USA"])          // Washington
println(capitals.getOrDefault("France", "Unknown"))  // Unknown

// Indexed access returns null for missing keys
val capital: String? = capitals["Brazil"]  // null

Use to to create pairs. The mutableMapOf variant allows modification:

val mutableCapitals = mutableMapOf(
    "USA" to "Washington"
)
mutableCapitals["Japan"] = "Tokyo"
mutableCapitals.remove("USA")

Construction Functions

Kotlin provides several ways to create collections:

val empty = emptyList<String>()
val singleton = listOf("only")
val filled = List(5) { it * 2 }  // [0, 2, 4, 6, 8]
val fromArray = listOf(*arrayOf(1, 2, 3))

The List(n) { transform } constructor creates a list of size n with each element computed by the transform lambda, where it is the index.

Map: Transforming Elements

map applies a function to each element and returns a new list with the results:

val numbers = listOf(1, 2, 3, 4, 5)
val doubled = numbers.map { it * 2 }
println(doubled)  // [2, 4, 6, 8, 10]

// With index
val indexed = numbers.mapIndexed { index, value ->
    "$index: $value"
}
println(indexed)  // [0: 1, 1: 2, 2: 3, 3: 4, 4: 5]

Filter: Selecting Elements

filter keeps elements that match a predicate. filterNot keeps elements that do not match:

val numbers = listOf(1, 2, 3, 4, 5, 6)
val evens = numbers.filter { it % 2 == 0 }
println(evens)  // [2, 4, 6]

val odds = numbers.filterNot { it % 2 == 0 }
println(odds)   // [1, 3, 5]

Reduce and Fold: Accumulating Results

reduce combines elements left-to-right using a function. The function takes the accumulated value and the current element:

val numbers = listOf(1, 2, 3, 4, 5)
val sum = numbers.reduce { acc, current -> acc + current }
println(sum)  // 15

fold is like reduce but starts with an initial value, allowing the accumulator type to differ from the element type:

val words = listOf("Hello", "World")
val sentence = words.fold("") { acc, word ->
    if (acc.isEmpty()) word else "$acc $word"
}
println(sentence)  // Hello World

Chaining Operations

Collection operations return new collections, so you can chain them for data pipelines:

val result = listOf(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
    .filter { it % 2 == 0 }     // [2, 4, 6, 8, 10]
    .map { it * it }             // [4, 16, 36, 64, 100]
    .filter { it > 20 }          // [36, 64, 100]
    .sum()                       // 200

Each operation produces an intermediate list. For performance-critical code, use asSequence() to chain operations lazily.

Grouping and Partitioning

groupBy groups elements by a key. partition splits into two lists based on a predicate:

val words = listOf("apple", "banana", "avocado", "blueberry")
val grouped = words.groupBy { it.first() }
println(grouped)  // {a=[apple, avocado], b=[banana, blueberry]}

val (startsA, rest) = words.partition { it.startsWith('a') }
println(startsA)  // [apple, avocado]
println(rest)     // [banana, blueberry]

Other Useful Operations

val numbers = listOf(3, 1, 4, 1, 5, 9, 2, 6)

println(numbers.sorted())       // [1, 1, 2, 3, 4, 5, 6, 9]
println(numbers.distinct())     // [3, 1, 4, 5, 9, 2, 6]
println(numbers.take(3))        // [3, 1, 4]
println(numbers.drop(3))        // [1, 5, 9, 2, 6]
println(numbers.any { it > 5 }) // true
println(numbers.all { it > 0 }) // true
println(numbers.none { it > 10 }) // true
println(numbers.count { it % 2 == 0 }) // 3
println(numbers.joinToString(", ")) // 3, 1, 4, 1, 5, 9, 2, 6