Функции области видимости

Объект контекста: this или it

Внутри лямбды функции области видимости объект контекста доступен по короткой ссылке вместо его фактического имени. Каждая функция области видимости использует один из двух способов доступа к объекту контекста: в качестве приемника лямбды (this) или в качестве аргумента лямбды (it). Оба обеспечивают одинаковые возможности, поэтому мы опишем преимущества и недостатки каждого для различных случаев и предоставим рекомендации по их использованию.

fun main() {
    val str = "Hello"
    // this
    str.run {
        println("The string's length: $length")
        //println("The string's length: ${this.length}") // does the same
    }

    // it
    str.let {
        println("The string's length is ${it.length}")
    }
}

data class Person(var name: String, var age: Int = 0, var city: String = "")

fun main() {
//sampleStart
    val adam = Person("Adam").apply { 
        age = 20                       // same as this.age = 20
        city = "London"
    }
    println(adam)
//sampleEnd
}

import kotlin.random.Random

fun writeToLog(message: String) {
    println("INFO: $message")
}

fun main() {
//sampleStart
    fun getRandomInt(): Int {
        return Random.nextInt(100).also {
            writeToLog("getRandomInt() generated value $it")
        }
    }
    
    val i = getRandomInt()
    println(i)
//sampleEnd
}

import kotlin.random.Random

fun writeToLog(message: String) {
    println("INFO: $message")
}

fun main() {
//sampleStart
    fun getRandomInt(): Int {
        return Random.nextInt(100).also { value ->
            writeToLog("getRandomInt() generated value $value")
        }
    }
    
    val i = getRandomInt()
    println(i)
//sampleEnd
}

Возвращаемое значение

Функции области видимости различаются по возвращаемому значению:

• apply и also возвращают объект контекста.

• let, run, и with возвращают результат лямбды.

Эти два варианта позволяют выбрать соответствующую функцию в зависимости от того, что вы делаете дальше в вашем коде.

fun main() {
//sampleStart
    val numberList = mutableListOf<Double>()
    numberList.also { println("Populating the list") }
        .apply {
            add(2.71)
            add(3.14)
            add(1.0)
        }
        .also { println("Sorting the list") }
        .sort()
//sampleEnd
    println(numberList)
}

import kotlin.random.Random

fun writeToLog(message: String) {
    println("INFO: $message")
}

fun main() {
//sampleStart
    fun getRandomInt(): Int {
        return Random.nextInt(100).also {
            writeToLog("getRandomInt() generated value $it")
        }
    }
    
    val i = getRandomInt()
//sampleEnd
}

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three")
    val countEndsWithE = numbers.run { 
        add("four")
        add("five")
        count { it.endsWith("e") }
    }
    println("There are $countEndsWithE elements that end with e.")
//sampleEnd
}

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three")
    with(numbers) {
        val firstItem = first()
        val lastItem = last()        
        println("First item: $firstItem, last item: $lastItem")
    }
//sampleEnd
}

let

Объект контекста доступен в качестве аргумента (it). Значение возврата — результат лямбды.

let можно использовать для вызова одной или нескольких функций над результатами цепочек вызовов. Например, следующий код выводит результаты двух операций над коллекцией:

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three", "four", "five")
    val resultList = numbers.map { it.length }.filter { it > 3 }
    println(resultList)    
//sampleEnd
}

С помощью let, вы можете переписать его так:

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three", "four", "five")
    numbers.map { it.length }.filter { it > 3 }.let { 
        println(it)
        // and more function calls if needed
    } 
//sampleEnd
}

Если блок кода содержит единственную функцию с it в качестве аргумента, вы можете использовать ссылку на метод (:: ) вместо лямбды:

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three", "four", "five")
    numbers.map { it.length }.filter { it > 3 }.let(::println)
//sampleEnd
}

let часто используется для выполнения блока кода только с ненулевыми значениями. Чтобы выполнить действия над ненулевым объектом, используйте оператор безопасного вызова ?. над ним и вызовите let с действиями в своей лямбде.

fun processNonNullString(str: String) {}

fun main() {
//sampleStart
    val str: String? = "Hello"   
    //processNonNullString(str)       // compilation error: str can be null
    val length = str?.let { 
        println("let() called on $it")        
        processNonNullString(it)      // OK: 'it' is not null inside '?.let { }'
        it.length
    }
//sampleEnd
}

Еще один случай использования let — введение локальных переменных с ограниченной областью видимости для улучшения читаемости кода. Чтобы определить новую переменную для объекта контекста, укажите её имя в качестве аргумента лямбды, чтобы она могла использоваться вместо значения по умолчанию it.

fun main() {
//sampleStart
    val numbers = listOf("one", "two", "three", "four")
    val modifiedFirstItem = numbers.first().let { firstItem ->
        println("The first item of the list is '$firstItem'")
        if (firstItem.length >= 5) firstItem else "!" + firstItem + "!"
    }.uppercase()
    println("First item after modifications: '$modifiedFirstItem'")
//sampleEnd
}

with

Функция без расширения: объект контекста передаётся в качестве аргумента, но внутри лямбды он доступен как получатель (this). Значение возврата — результат лямбды.

Мы рекомендуем with для вызова функций над объектом контекста без предоставления результата лямбды. В коде with можно прочитать как «с этим объектом, выполните следующее.»

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three")
    with(numbers) {
        println("'with' is called with argument $this")
        println("It contains $size elements")
    }
//sampleEnd
}

Ещё один случай использования with — введение вспомогательного объекта, свойства или функции которого будут использованы для вычисления значения.

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three")
    val firstAndLast = with(numbers) {
        "The first element is ${first()}," +
        " the last element is ${last()}"
    }
    println(firstAndLast)
//sampleEnd
}

run

Объект контекста доступен как получатель (this). Значение возврата — результат лямбды.

run делает то же, что и with, но вызывается как let — как функция расширения объекта контекста.

run полезно, когда ваша лямбда содержит как инициализацию объекта, так и вычисление возвращаемого значения.

class MultiportService(var url: String, var port: Int) {
    fun prepareRequest(): String = "Default request"
    fun query(request: String): String = "Result for query '$request'"
}

fun main() {
//sampleStart
    val service = MultiportService("https://example.kotlinlang.org", 80)

    val result = service.run {
        port = 8080
        query(prepareRequest() + " to port $port")
    }
    
    // the same code written with let() function:
    val letResult = service.let {
        it.port = 8080
        it.query(it.prepareRequest() + " to port ${it.port}")
    }
//sampleEnd
    println(result)
    println(letResult)
}

Помимо вызова run на объекте-получателе, вы можете использовать его как функцию без расширения. Функция без расширения run позволяет выполнить блок нескольких инструкций, где требуется выражение.

fun main() {
//sampleStart
    val hexNumberRegex = run {
        val digits = "0-9"
        val hexDigits = "A-Fa-f"
        val sign = "+-"
        
        Regex("[$sign]?[$digits$hexDigits]+")
    }
    
    for (match in hexNumberRegex.findAll("+123 -FFFF !%*& 88 XYZ")) {
        println(match.value)
    }
//sampleEnd
}

apply

Объект контекста доступен как получатель (this). Значение возврата — сам объект.

Используйте apply для блоков кода, которые не возвращают значение и в основном работают с членами объекта-получателя. Общий случай для apply — конфигурация объекта. Такие вызовы можно интерпретировать как «применить следующие присвоения к объекту.»

data class Person(var name: String, var age: Int = 0, var city: String = "")

fun main() {
//sampleStart
    val adam = Person("Adam").apply {
        age = 32
        city = "London"        
    }
    println(adam)
//sampleEnd
}

Имея получателя в качестве возвращаемого значения, вы можете легко включить apply в цепочки вызовов для более сложной обработки.

also

Объект контекста доступен в качестве аргумента (it). Значение возврата — сам объект.

also хорошо подходит для выполнения некоторых действий, принимающих объект контекста в качестве аргумента. Используйте also для действий, которые требуют ссылки на объект, а не его свойств и функций, или когда вы не хотите затенять ссылку this из внешней области видимости.

Когда вы видите also в коде, вы можете прочитать его как «и также выполните следующее с объектом.»

fun main() {
//sampleStart
    val numbers = mutableListOf("one", "two", "three")
    numbers
        .also { println("The list elements before adding new one: $it") }
        .add("four")
//sampleEnd
}