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

Объект контекста: 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
}

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

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

let часто используется для выполнения блока кода, содержащего значения, отличные от null. Чтобы выполнить действия над объектом, отличным от null, используйте оператор безопасного вызова ?. и вызовите 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 не является функцией расширения: объект контекста передаётся в качестве аргумента, но внутри лямбды он доступен как получатель (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 не имеет объекта контекста, но всё равно возвращает результат лямбды. Функция без расширения 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 — включение 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
}