A Kotlin list keeps elements in order. Use List when callers only need to read values, and MutableList when code must add, replace, or otherwise change them. This split makes mutation visible in an API while retaining direct compatibility with Java collection classes. section 3.1 section 8.2.3
Create and update a list
```kotlin val names = mutableListOf("Martin", "Samuel") names.replaceAll { it.uppercase() } // [MARTIN, SAMUEL] names.fill("(redacted)") // [(redacted), (redacted)] ``` `mutableListOf` creates a mutable list. `replaceAll` computes a replacement for every element; `fill` is the shorter choice when every element receives the same value. section 6.1.7
Choose the interface from the operations a function needs:
- Accept `List<T>` to inspect elements without exposing mutating operations. Read-only lists support operations such as `last()`, `shuffled()`, and numeric `sum()`. section 3.1
- Accept `MutableList<T>` when the function must add or replace elements. A mutable interface also extends its corresponding read-only interface. section 8.2.3
- Prefer collections to arrays by default; Kotlin and Java collection values can be passed across the language boundary without conversion. section 8.2.4
Mutability matters to generic type safety. A `List<String>` can be passed where `List<Any>` is expected because reading strings as `Any` is safe. A `MutableList<String>` cannot be passed as `MutableList<Any>`: code receiving it could insert an integer and corrupt the list’s promised element type. section 11.3.1 section 11.4
Model missing parsed values
```kotlin fun readNumbers(text: String): List<Int?> { val result = mutableListOf<Int?>() for (line in text.lineSequence()) { result.add(line.toIntOrNull()) } return result } ``` `List<Int?>` means the list exists but individual entries may be absent. This differs from `List<Int>?`, where the list reference itself may be absent. Use `filterNotNull()` when later work needs only valid, non-null values. section 8.2.1
Java declarations may not state whether a collection is nullable, whether its elements are nullable, or whether callers may mutate it. When implementing such APIs, select the Kotlin type that matches the actual contract—for example, `MutableList<Person>` for output and `MutableList<String?>` for optional per-item errors. section 8.2.4
Table 8.2 Collection-creation functions (view table figure)
Compare the factory functions for read-only and mutable lists alongside Kotlin’s corresponding set and map types. section 8.2.3
