Kotlin Destructuring Declaration

A destructuring declaration is a syntax mechanism in Kotlin that unpacks a single composite object into multiple distinct variables simultaneously. It operates by invoking positional componentN() functions defined on the source object, mapping each extracted value to a corresponding variable in the declaration.

val (variable1, variable2, variable3) = objectInstance

Compiler Translation

Destructuring is a convention-based feature. When the Kotlin compiler encounters a destructuring declaration, it translates the syntax into sequential calls to component1(), component2(), and so forth.

// Source syntax
val (x, y) = coordinates

// Compiled equivalent
val x = coordinates.component1()
val y = coordinates.component2()

The `componentN()` Operator

For an object to be destructurable, its class must provide componentN() functions. These functions are subject to strict compiler requirements:

They must be prefixed with the operator modifier.
They must be callable without arguments.
The return type of the componentN() function dictates the type of the resulting variable.

These functions can be defined either as member functions within the class or as extension functions.

Manual Implementation

To enable destructuring on a standard class, you must explicitly define the operator functions:

class Vector3D(val x: Float, val y: Float, val z: Float) {
    operator fun component1(): Float = x
    operator fun component2(): Float = y
    operator fun component3(): Float = z
}

val (i, j, k) = Vector3D(1.0f, 0.0f, 0.5f)

Extension Function Implementation

If you do not own the source code of a class, you can provide destructuring capabilities via extension functions. For example, adding destructuring to the standard Java File class:

import java.io.File

operator fun File.component1(): String = this.name
operator fun File.component2(): String? = this.parent

val (fileName, parentDirectory) = File("/var/log/syslog")

Data Classes

When a class is declared with the data modifier, the Kotlin compiler automatically synthesizes the componentN() functions. These functions are generated exclusively for the properties defined in the primary constructor, strictly following their declaration order.

data class Session(val id: String, val token: String, val expiresAt: Long)

val session = Session("user_123", "abc.def.ghi", 1672531199L)
val (id, token, expiration) = session 

Note: Properties defined in the class body are excluded from the generated componentN() functions.

Destructuring in Control Flow and Lambdas

Destructuring declarations are natively supported in for loops and lambda expressions, provided the underlying collection elements or lambda parameters possess the requisite componentN() functions.

`for` Loops

When iterating over a collection, the loop variable can be destructured. This is commonly used with Map, as the Kotlin Standard Library provides component1() and component2() extensions for Map.Entry.

val config = mapOf("host" to "localhost", "port" to "8080")

for ((key, value) in config) {
    println("$key -> $value")
}

Lambdas

In higher-order functions, a lambda parameter can be destructured by wrapping the parameter names in parentheses.

config.forEach { (key, value) ->
    println("$key -> $value")
}

If the lambda expects two distinct parameters rather than a single destructurable object, parentheses are omitted. The presence of parentheses explicitly instructs the compiler to invoke componentN() on a single incoming parameter.

Ignoring Components

If a specific component in the destructuring sequence is not needed, you can substitute the variable name with an underscore (_). This is a compiler-level optimization; the compiler will skip the generation of the corresponding componentN() call entirely, avoiding unnecessary allocations or computations.