liveBook · Manning

Captured variable

As explained in Kotlin in Action, 2E

A captured variable is a variable that stores the subject of a Kotlin when expression and is accessible within that expression's branches.

A captured variable is a value made available beyond its immediate declaration context. Kotlin uses the term for a when subject bound inside the expression and for external variables retained by a lambda. section 2.3.3 section 5.1.4

Listing 2.14 Assigning the subject of a when to a variable
import ch02.colors.Color.*                                   #1
 
fun measureColor() = ORANGE
 
fun getWarmthFromSensor() =
    when (val color = measureColor()) {                      #2
        RED, ORANGE, YELLOW -> "warm (red = ${color.r})"     #3
        GREEN -> "neutral (green = ${color.g})"
        BLUE, INDIGO, VIOLET -> "cold (blue = ${color.b}"
    }

Bind the result of measureColor() directly in the when expression. The variable remains scoped to the expression while its properties remain available in each branch. section 2.3.3

Use a captured when subject to avoid an unrelated variable in surrounding code. When the when result is assigned or returned, every possible path must produce a value; covering all enum constants or adding else satisfies exhaustiveness. section 2.3.3

Capturing variables in a lambda

fun printProblemCounts(responses: Collection<String>) { var clientErrors = 0 var serverErrors = 0 responses.forEach { if (it.startsWith("4")) clientErrors++ else if (it.startsWith("5")) serverErrors++ } println("$clientErrors client errors, $serverErrors server errors") } section 5.1.4

Unlike Java, Kotlin lambdas can capture and modify nonfinal local variables. A captured val is stored with the lambda; a captured var uses a wrapper so later executions can observe its updated value. Capturing can also affect Java interoperation: a lambda passed to a Java method may require a new object per call when it captures a surrounding value. section 5.1.4 section 5.2.1

How Kotlin in Action, 2E covers it

How deep it goes
Defines scope, exhaustiveness, mutable capture wrappers, and Java object creation, while deferring inline-function details.
Examples
Uses a color-reading when expression, error counters inside forEach, and deferred Runnable computation.
What it assumes
Assumes basic Kotlin variables, when expressions, lambdas, and Java method calls; teaches capture mechanics explicitly.
What you can do after
Apply it by binding when subjects locally and reading or mutating surrounding variables from Kotlin lambdas.
How it connects
Connects when expressions with enums, lambdas, closures, Java functional interfaces, and inline functions.
Cover of Kotlin in Action, 2E
liveBookmanning.com
Read Kotlin in Action, 2E on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Kotlin in Action, 2E. The section links point to the parts of the book it draws on.