Расширения

Получатели

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

Например, функция-расширение .appendLine() из стандартной библиотеки расширяет класс StringBuilder. В этом случае получателем является экземпляр StringBuilder, а тип получателя — StringBuilder:

fun main() { 
//sampleStart
    // builder is an instance of StringBuilder
    val builder = StringBuilder()
        // Calls .appendLine() extension function on builder
        .appendLine("Hello")
        .appendLine()
        .appendLine("World")
    println(builder.toString())
    // Hello
    //
    // World
}
//sampleEnd

Функции-расширения

Прежде чем создавать собственные функции-расширения, проверьте, нет ли нужной вам функции в стандартной библиотеке Kotlin. Стандартная библиотека предоставляет множество полезных функций-расширений для:

• Работы с коллекциями: .map(), .filter(), .reduce(), .fold(), .groupBy().

• Преобразования в строки: .joinToString().

• Работы с null-значениями: .filterNotNull().

Чтобы создать собственную функцию-расширение, укажите перед её именем тип получателя, а затем .. В этом примере функция .truncate() расширяет класс String, поэтому тип получателя — String:

fun String.truncate(maxLength: Int): String {
    return if (this.length <= maxLength) this else take(maxLength - 3) + "..."
}

fun main() {
    val shortUsername = "KotlinFan42"
    val longUsername = "JetBrainsLoverForever"

    println("Short username: ${shortUsername.truncate(15)}") 
    // KotlinFan42
    println("Long username:  ${longUsername.truncate(15)}")
    // JetBrainsLov...
}

Функция .truncate() усекает строку, для которой она вызвана, до количества символов, заданного аргументом maxLength, и добавляет многоточие .... Если строка короче maxLength, функция возвращает исходную строку.

В этом примере функция .displayInfo() расширяет интерфейс User:

interface User {
    val name: String
    val email: String
}

fun User.displayInfo(): String = "User(name=$name, email=$email)"

// Inherits from and implements the properties of the User interface
class RegularUser(override val name: String, override val email: String) : User

fun main() {
    val user = RegularUser("Alice", "alice@example.com")
    println(user.displayInfo()) 
    // User(name=Alice, email=alice@example.com)
}

Функция .displayInfo() возвращает строку, содержащую name и email экземпляра RegularUser. Определение расширения интерфейса, как в этом примере, полезно, когда требуется один раз добавить функциональность всем типам, реализующим этот интерфейс.

В этом примере функция .mostVoted() расширяет класс Map<String, Int>:

fun Map<String, Int>.mostVoted(): String? {
    return maxByOrNull { (key, value) -> value }?.key
}

fun main() {
    val poll = mapOf(
        "Cats" to 37,
        "Dogs" to 58,
        "Birds" to 22
    )

    println("Top choice: ${poll.mostVoted()}") 
    // Dogs
}

Функция .mostVoted() перебирает пары «ключ-значение» карты, для которой она вызвана, и использует функцию maxByOrNull(), чтобы вернуть ключ пары с наибольшим значением. Если карта пуста, функция maxByOrNull() возвращает null. Функция mostVoted() использует безопасный вызов ?., чтобы обращаться к свойству key только в том случае, если функция maxByOrNull() возвращает ненулевое значение.

fun <T> List<T>.endpoints(): Pair<T, T> {
    return first() to last()
}

fun main() {
    val cities = listOf("Paris", "London", "Berlin", "Prague")
    val temperatures = listOf(21.0, 19.5, 22.3)

    val cityEndpoints = cities.endpoints()
    val tempEndpoints = temperatures.endpoints()

    println("First and last cities: $cityEndpoints")
    // (Paris, Prague)
    println("First and last temperatures: $tempEndpoints") 
    // (21.0, 22.3)
}

fun main() {
    //sampleStart
    // Extension function on nullable Any
    fun Any?.toString(): String {
        if (this == null) return "null"
        // After null check, `this` is smart-cast to non-nullable Any
        // So this call resolves to the regular toString() function
        return toString()
    }
    
    val number: Int? = 42
    val nothing: Any? = null
    
    println(number.toString())
    // 42
    println(nothing.toString()) 
    // null
    //sampleEnd
}

fun main() {
//sampleStart
    open class Shape
    class Rectangle: Shape()
    
    fun Shape.getName() = "Shape"
    fun Rectangle.getName() = "Rectangle"
    
    fun printClassName(shape: Shape) {
        println(shape.getName())
    }
    
    printClassName(Rectangle())
    // Shape
//sampleEnd
}

fun main() {
//sampleStart
    class Example {
        fun printFunctionType() { println("Member function") }
    }
    
    fun Example.printFunctionType() { println("Extension function") }
    
    Example().printFunctionType()
    // Member function
//sampleEnd
}

fun main() {
//sampleStart
    class Example {
        fun printFunctionType() { println("Member function") }
    }
    
    // Same name but different signature
    fun Example.printFunctionType(index: Int) { println("Extension function #$index") }
    
    Example().printFunctionType(1)
    // Extension function #1
//sampleEnd
}

fun main() {
    //sampleStart
    data class Order(val weight: Double)
    val calculateShipping = fun Order.(rate: Double): Double = this.weight * rate
    
    val order = Order(2.5)
    val cost = order.calculateShipping(3.0)
    println("Shipping cost: $cost") 
    // Shipping cost: 7.5
}

fun main() {
    val isInRange: Int.(min: Int, max: Int) -> Boolean = { min, max -> this in min..max }

    println(5.isInRange(1, 10))
    // true
    println(20.isInRange(1, 10))
    // false
}

Свойства-расширения

Kotlin поддерживает свойства-расширения, которые полезны для преобразования данных или создания вспомогательных элементов пользовательского интерфейса, не загромождая класс, с которым вы работаете.

Чтобы создать свойство-расширение, укажите имя класса, который хотите расширить, затем . и имя свойства.

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

data class User(val firstName: String, val lastName: String)

// An extension property to get a username-style email handle
val User.emailUsername: String
    get() = "${firstName.lowercase()}.${lastName.lowercase()}"

fun main() {
    val user = User("Mickey", "Mouse")
    // Calls extension property
    println("Generated email username: ${user.emailUsername}")
    // Generated email username: mickey.mouse
}

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

data class House(val streetName: String)

// Doesn't compile because there is no getter and setter
// var House.number = 1
// Error: Initializers are not allowed for extension properties

// Compiles successfully
val houseNumbers = mutableMapOf<House, Int>()
var House.number: Int
    get() = houseNumbers[this] ?: 1
    set(value) {
        println("Setting house number for ${this.streetName} to $value")
        houseNumbers[this] = value
    }

fun main() {
    val house = House("Maple Street")

    // Shows the default
    println("Default number: ${house.number} ${house.streetName}") 
    // Default number: 1 Maple Street
    
    house.number = 99
    // Setting house number for Maple Street to 99

    // Shows the updated number
    println("Updated number: ${house.number} ${house.streetName}") 
    // Updated number: 99 Maple Street
}

В этом примере геттер использует оператор Элвиса, чтобы вернуть номер дома, если он есть в карте houseNumbers, или 1. Подробнее о том, как писать геттеры и сеттеры, см. в разделе Пользовательские геттеры и сеттеры.

Расширения объектов-компаньонов

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

class Logger {
    companion object { }
}

fun Logger.Companion.logStartupMessage() {
    println("Application started.")
}

fun main() {
    Logger.logStartupMessage()
    // Application started.
}

Объявление расширений в качестве членов

Можно объявлять расширения одного класса внутри другого. У таких расширений несколько неявных получателей. Неявный получатель — это объект, к членам которого можно обращаться без квалификации с помощью this:

• Класс, в котором объявлено расширение, является получателем диспетчеризации.

• Тип получателя функции-расширения является получателем расширения.

Рассмотрим пример, в котором класс Connection содержит функцию-расширение для класса Host с именем printConnectionString():

class Host(val hostname: String) {
    fun printHostname() { print(hostname) }
}

class Connection(val host: Host, val port: Int) {
    fun printPort() { print(port) }

    // Host is the extension receiver
    fun Host.printConnectionString() {
        // Calls Host.printHostname()
        printHostname() 
        print(":")
        // Calls Connection.printPort()
        // Connection is the dispatch receiver
        printPort()
    }

    fun connect() {
        /*...*/
        // Calls the extension function
        host.printConnectionString() 
    }
}

fun main() {
    Connection(Host("kotl.in"), 443).connect()
    // kotl.in:443
    
    // Triggers an error because the extension function isn't available outside Connection
    // Host("kotl.in").printConnectionString()
    // Unresolved reference 'printConnectionString'.
}

В этом примере функция printConnectionString() объявлена внутри класса Connection, поэтому класс Connection является получателем диспетчеризации. Тип получателя функции-расширения — класс Host, поэтому класс Host является получателем расширения.

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

class Connection {
    fun Host.getConnectionString() {
        // Calls Host.toString()
        toString()
        // Calls Connection.toString()
        this@Connection.toString()
    }
}

open class User

class Admin : User()

open class NotificationSender {
    open fun User.sendNotification() {
        println("Sending user notification from normal sender")
    }

    open fun Admin.sendNotification() {
        println("Sending admin notification from normal sender")
    }

    fun notify(user: User) {
        user.sendNotification()
    }
}

class SpecialNotificationSender : NotificationSender() {
    override fun User.sendNotification() {
        println("Sending user notification from special sender")
    }

    override fun Admin.sendNotification() {
        println("Sending admin notification from special sender")
    }
}

fun main() {
    // Dispatch receiver is NotificationSender
    // Extension receiver is User
    // Resolves to User.sendNotification() in NotificationSender
    NotificationSender().notify(User())
    // Sending user notification from normal sender
    
    // Dispatch receiver is SpecialNotificationSender
    // Extension receiver is User
    // Resolves to User.sendNotification() in SpecialNotificationSender
    SpecialNotificationSender().notify(User())
    // Sending user notification from special sender 
    
    // Dispatch receiver is SpecialNotificationSender
    // Extension receiver is User NOT Admin
    // The notify() function declares user as type User
    // Statically resolves to User.sendNotification() in SpecialNotificationSender
    SpecialNotificationSender().notify(Admin())
    // Sending user notification from special sender 
}

Расширения и модификаторы видимости

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

Например, расширение, объявленное на верхнем уровне файла, может обращаться к другим объявлениям верхнего уровня private в том же файле:

// File: StringUtils.kt

private fun removeWhitespace(input: String): String {
    return input.replace("\\s".toRegex(), "")
}

fun String.cleaned(): String {
    return removeWhitespace(this)
}

fun main() {
    val rawEmail = "  user @example. com  "
    val cleaned = rawEmail.cleaned()
    println("Raw:     '$rawEmail'")
    // Raw:     '  user @example. com  '
    println("Cleaned: '$cleaned'")
    // Cleaned: 'user@example.com'
    println("Looks like an email: ${cleaned.contains("@") && cleaned.contains(".")}") 
    // Looks like an email: true
}

А если расширение объявлено вне типа получателя, оно не может обращаться к членам private или protected получателя:

class User(private val password: String) {
    fun isLoggedIn(): Boolean = true
    fun passwordLength(): Int = password.length
}

// Extension declared outside the class
fun User.isSecure(): Boolean {
    // Can't access password because it's private:
    // return password.length >= 8

    // Instead, we rely on public members:
    return passwordLength() >= 8 && isLoggedIn()
}

fun main() {
    val user = User("supersecret")
    println("Is user secure: ${user.isSecure()}") 
    // Is user secure: true
}

Если расширение помечено как internal, оно доступно только в пределах своего модуля:

// Networking module
// JsonParser.kt
internal fun String.parseJson(): Map<String, Any> {
    return mapOf("fakeKey" to "fakeValue")
}

Область видимости расширений

В большинстве случаев расширения определяются на верхнем уровне, непосредственно внутри пакетов:

package org.example.declarations

fun List<String>.getLongestString() { /*...*/}

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

package org.example.usage

import org.example.declarations.getLongestString

fun main() {
    val list = listOf("red", "green", "blue")
    list.getLongestString()
}

Дополнительную информацию см. в разделе Импорт.