Destructuring declaration — o que é, sintaxe e uso em Kotlin

O que é destructuring declaration?

Destructuring declaration (declaração de desestruturação) é uma construção sintática do Kotlin que permite decompor uma instância de classe em várias variáveis em uma única expressão. O lado esquerdo contém uma lista de variáveis entre parênteses, o lado direito contém o objeto sendo decomposto. O Kotlin chama automaticamente a função componentN() correspondente para cada variável, onde N é o número ordinal da variável entre parênteses.

A declaração de desestruturação é mais comumente usada com data classes. O compilador Kotlin gera automaticamente component1(), component2() e assim por diante para cada data class — com base no número de propriedades no construtor primário. Para classes regulares sem o modificador data, componentN() não são gerados, mas podem ser definidos manualmente como funções operadoras com a palavra-chave operator.

A declaração de desestruturação tornou-se um padrão popular devido à sua capacidade de simplificar o código ao trabalhar com coleções de pares, resultados de funções e iteração de Map. Em vez de escrever person.firstName, person.lastName, o desenvolvedor escreve val (firstName, lastName) = person. Isso reduz o número de linhas e melhora a legibilidade, especialmente em loops e lambdas.

Como funciona a desestruturação em Kotlin?

Ao encontrar a construção val (a, b) = obj, o compilador Kotlin gera o seguinte código: val a = obj.component1(); val b = obj.component2(). Se as variáveis forem declaradas com var, atribuições var são geradas. O tipo de cada variável é inferido a partir do tipo de retorno da função componentN() correspondente. Isso significa que a declaração de desestruturação é totalmente type-safe e verificada em tempo de compilação.

data class Person(val firstName: String, val lastName: String, val age: Int)

fun main() {
    val person = Person("Alice", "Smith", 30)

    // Desestruturação: component1(), component2(), component3()
    val (firstName, lastName, age) = person
    println("$firstName $lastName, $age anos")
}

Na listagem, Person é uma data class com três propriedades. Kotlin gera component1() → firstName, component2() → lastName, component3() → age. A expressão val (firstName, lastName, age) = person chama essas funções e atribui os resultados. Importante: os nomes das variáveis não precisam corresponder aos nomes das propriedades — o compilador observa apenas a ordem de componentN() e seus tipos. Você pode decompor apenas as primeiras N propriedades, ignorando o restante.

Desestruturação de data classes e tipos padrão

As data classes são os principais candidatos para a declaração de desestruturação. Cada data class obtém automaticamente componentN() para todas as propriedades do construtor primário. A ordem de componentN() corresponde à ordem de declaração das propriedades. Isso significa que ao alterar a ordem dos campos em uma data class, a ordem das variáveis na desestruturação também muda — o que pode levar a bugs sutis.

// Desestruturação de Pair
val pair = Pair("key", 42)
val (key, value) = pair
println("$key -> $value")

// Desestruturação de Triple
val triple = Triple("A", "B", "C")
val (first, second, third) = triple

// Map.Entry em loop
val map = mapOf("a" to 1, "b" to 2)
for ((k, v) in map) {
    println("$k = $v")
}

Pair e Triple são classes padrão com desestruturação embutida para dois e três componentes. Pair é frequentemente usado como tipo de retorno para funções que precisam retornar dois valores relacionados sem criar uma data class separada. Em um loop for sobre Map.Entry, a construção (k, v) = entry desestrutura a chave e o valor por meio de component1() e component2(). Este é o padrão padrão para iterar sobre um Map em Kotlin, substituindo completamente as chamadas explícitas a key e value.

Sublinhado para variáveis não utilizadas

Se alguns componentes não forem necessários durante a desestruturação, o Kotlin permite substituí-los por um sublinhado _. Isso melhora a legibilidade — o leitor vê imediatamente que o componente está sendo ignorado. Além disso, o uso de _ impede o acesso acidental a uma variável não inicializada: o compilador não cria nenhuma variável para _, eliminando avisos sobre variáveis não utilizadas.

data class Order(
    val id: Long,
    val customerName: String,
    val amount: Double,
    val status: String
)

fun process(orders: List<Order>) {
    for ((id, _, amount) in orders) {
        println("Pedido $id: $amount")
    }
}

Na listagem, Order tem quatro propriedades, mas o loop precisa apenas de id e amount. O sublinhado no lugar de customerName diz ao compilador “pule component2()”. Kotlin não chama component2() e não cria uma variável para este componente. Importante: sublinhados só podem ser usados em declarações de desestruturação, não no construtor da data class. Se vários componentes consecutivos forem pulados, cada um recebe seu próprio sublinhado.

Criação de componentN() para classes personalizadas

Para classes sem o modificador data, você pode definir manualmente componentN() adicionando a palavra-chave operator. Isso permite usar a declaração de desestruturação com qualquer classe, incluindo classes de terceiros cujo código fonte não pode ser modificado — basta escrever uma função de extensão com operator. Essa abordagem é especialmente útil para classes de bibliotecas e classes Java que não possuem componentN() automáticos.

class Rect(val width: Int, val height: Int)

operator fun Rect.component1(): Int = width
operator fun Rect.component2(): Int = height

// Para classe Java com getters
operator fun Dimension.component1(): Int = width
operator fun Dimension.component2(): Int = height

fun main() {
    val rect = Rect(1920, 1080)
    val (w, h) = rect
    println("Resolução: ${w}x${h}")
}

No exemplo, Rect é uma classe regular sem data. Funções de extensão com operator fun component1() = width e component2() = height adicionam suporte a desestruturação. Da mesma forma para java.awt.Dimension: uma extensão operator em Dimension permite decompor em width e height. Limitação: o número máximo de componentes para declaração de desestruturação é 5. Em teoria, você pode definir component6() e acima, mas Kotlin não gerará a sintaxe correspondente para 6+ variáveis entre parênteses.