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

Объект контекста: 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, примените к нему оператор безопасного вызова ?. и вызовите 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, не являющаяся функцией-расширением, позволяет выполнить блок из нескольких инструкций там, где требуется выражение. В коде 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
}