O que são as 'funções de escopo' em Kotlin e quando devem ser usadas?

As funções de escopo permitem executar um bloco de código no contexto de um objeto. As funções principais são: let, run, with, apply, also. Cada uma tem as suas próprias características em relação ao recetor (invocador, receptor) e ao valor de retorno.

Função	Recetor	Valor de retorno
let	it	O resultado da última expressão no bloco
run	this	O resultado da última expressão no bloco
with	this (não como método de extensão)	O resultado da última expressão no bloco
apply	this	O próprio objeto configurado
also	it	O próprio objeto configurado

Utilização:

• let: Para realizar ações sobre um objeto que pode ser null, ou para introduzir uma variável local com um nome mais curto.

// Exemplo: chamada segura de método em um objeto nullable
val str: String? = "Hello"
str?.let {
    println(it.length) // Executa apenas se str não for null
}

• run: Para executar um bloco de código com o contexto do objeto (como with), mas como método de extensão, ou quando se deseja calcular um valor no contexto do objeto.

// Exemplo: configuração de objeto e obtenção do resultado
val configurations = buildList {
    add("Config 1")
    add("Config 2")
}.run {
    println("Applying configurations...")
    joinToString(", ") // Executa no contexto de List<String>, retorna String
}
println(configurations)

• with: Para agrupar chamadas de métodos de um objeto sem usar "ponto" antes de cada chamada. Não é um método de extensão.

// Exemplo: agrupamento de chamadas de métodos de um mesmo objeto
val person = Person("Alice", 30)
with(person) {
    println(name) // Acesso direto às propriedades
    println(age)
}

• apply: Para configurar um objeto. Retorna o próprio objeto configurado. Útil para criar e inicializar objetos em uma única expressão.

// Exemplo: criação e configuração de um objeto em um passo
val button = Button().apply {
    text = "Click Me"
    onClick = { println("Button clicked") }
}

• also: Para realizar ações adicionais sobre um objeto, como logging, após alguma operação. Retorna o próprio objeto.

// Exemplo: logging após realizar uma ação
val number = 42
val squared = number.also {
    println("Processing number: $it") // Executa sobre it (number), retorna number
}.run {
    this * this // Executa sobre this (number), retorna o quadrado
}
println("Squared value: $squared")

A escolha da função de escopo adequada depende do que se deseja fazer com o objeto e qual valor deve ser retornado.