Введенов

Начиная с Kotlin: 2.3

@Target(allowedTargets = [AnnotationTarget.VALUE_PARAMETER])
annotation class IntroducedAt(val version: String)

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

Предполагается, что параметры-значения с одинаковой версией были введены одновременно. Например, для сигнатуры

fun example(a: A, @IntroducedAt("1.1") b: B = defaultB, @IntroducedAt("1.1") c: C = defaultC, @IntroducedAt("1.4") d: D = defaultD)

компилятор создает перегрузки, соответствующие следующему:

fun example(a: A) // hidden, initial version
fun example(a: A, @IntroducedAt("1.1") b: B = defaultB, @IntroducedAt("1.1") c: C = defaultC) // hidden, version 1.1

// non-hidden overload, version 1.4
fun example(a: A, @IntroducedAt("1.1") b: B = defaultB, @IntroducedAt("1.1") c: C = defaultC, @IntroducedAt("1.4") d: D = defaultD)

Обратите внимание: как только пользователь библиотеки скомпилирует код с новой версией, для генерации кода будет выбрана самая новая перегрузка (содержащая все необязательные параметры). Это означает, что с этого момента более старая версия библиотеки может стать непригодной в качестве зависимости.

Ограничения на IntroducedAt

Строка версии должна соответствовать формату версий Apache Maven. Версии в сигнатуре должны быть указаны в порядке возрастания.

• Предполагается, что параметры без этой аннотации соответствуют «исходной версии».

• Если последний параметр имеет функциональный тип, это правило можно не применять. Это позволяет вводить необязательные параметры перед позицией лямбды в конце.

Эту аннотацию нельзя использовать для получателей расширений или контекстных параметров — только для параметров-значений.

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

Эту аннотацию нельзя использовать для не-final методов, включая абстрактные методы и методы интерфейсов. Эти ограничения аналогичны ограничениям для kotlin.jvm.JvmName.

Эту аннотацию нельзя использовать вместе с kotlin.jvm.JvmOverloads.

Если конструктор класса данных содержит параметры, помеченные этой аннотацией, компилятор также создает соответствующие перегрузки метода copy в дополнение к перегрузкам конструктора.

Дополнительную информацию см. в полном документе с описанием проекта (KEEP).