Returning more than one value from a method in Java is awkward — you build a little class, or abuse an array, or reach for Map.Entry. And on the receiving end you pull the pieces out one accessor call at a time. Kotlin lets you unpack an object into several variables in a single line. It’s a small feature, but it shows up constantly once you have it.

This post follows equality, and leans on the data class from the class-types tour.

The basic form

A destructuring declaration assigns several variables from one object, with the names in parentheses:

val (id, name) = user

That’s shorthand for two declarations: val id = user.component1() and val name = user.component2(). The unpacking is positional — id gets the first component, name the second — and the variable names are yours to choose; they don’t have to match the property names.

Where the components come from

Destructuring works on any type that provides component1(), component2(), and so on. You rarely write those yourself, because a data class generates one per property in its primary constructor:

data class User(val id: Int, val name: String)

val (id, name) = User(1, "Ada")

This is the clean way to return several values from a function — declare a small data class, return it, and let the caller destructure:

data class MinMax(val min: Int, val max: Int)

fun range(numbers: List<Int>) = MinMax(numbers.min(), numbers.max())

val (low, high) = range(scores)

Pairs and triples work too, but a named data class reads far better than Pair<Int, Int> at the call site, where first and second tell you nothing.

In loops

Destructuring really earns its place in for loops. Iterating a map gives you entries, and each entry destructures into key and value:

for ((name, age) in ages) {
    println("$name is $age")
}

The withIndex() helper we saw with loops does the same with an index and a value:

for ((i, name) in names.withIndex()) {
    println("$i: $name")
}

Skipping and limits

If you don’t need a component, name it _ and the compiler skips the call:

val (_, name, email) = user      // ignore the first

Two limits keep it honest. It’s positional, not by-name, so the order of properties in the class matters — reorder them and you silently swap your variables. And there’s no partial match: val (a, b) needs component1 and component2 to exist. For objects with many fields, destructuring a handful of them by position gets fragile fast; that’s a sign to access them by name instead.

Your own components

Destructuring works on anything that defines componentN operator functions. A data class writes them for you, but you can add them to a regular class — or even to a type you don’t own, through an extension:

class Color(val rgb: Int) {
    operator fun component1() = (rgb shr 16) and 0xFF   // red
    operator fun component2() = (rgb shr 8) and 0xFF    // green
    operator fun component3() = rgb and 0xFF            // blue
}

val (r, g, b) = Color(0xFF8800)

This is the same operator mechanism behind + and [] — destructuring is sugar over a naming convention, with no magic underneath.

Destructuring in chains

Because a lambda parameter can be destructured, transformations read cleanly when the elements are pairs or data objects:

val users = listOf(User(1, "Ada"), User(2, "Linus"))

users.forEach { (id, name) -> println("$id: $name") }
users.associate { (id, name) -> name to id }      // {"Ada"=1, "Linus"=2}

A worked example

Destructuring shines at the boundary where data arrives in clumps — splitting a line, then naming the pieces you just produced:

data class Entry(val key: String, val value: String)

fun parse(line: String): Entry {
    val (key, value) = line.split("=", limit = 2)   // a List destructures too
    return Entry(key.trim(), value.trim())
}

val (k, v) = parse("  host = example.com ")         // k = "host", v = "example.com"

split returns a list, and the declaration pulls its first two elements positionally — List itself provides component1 through component5, which is why this works.

Final thoughts

Destructuring is syntactic sugar over the componentN convention, and it’s at its best exactly where it’s safe: small data classes and map entries, where the components have an obvious order and there are only a few of them. Used there, it turns multi-value returns and map iteration into one-liners that read cleanly. Pushed onto wide objects, it trades that clarity for fragility — so keep it small.

Next, something more structural: how Kotlin controls what’s visible to whom, including a visibility level Java doesn’t have. That’s visibility and packages.

Practice: reinforce this with the companion workbook — short, click-to-reveal problems.