Kotlin language specification

Overload resolution

Glossary

type(e)

Type of expression e

Introduction

Note: most of this section explains the overload resolution process for callables, as the overload resolution process for properties uses the same framework. Important differences w.r.t. properties are covered in the corresponding section.

Basics

Receivers

• Any receiver available in a scope is available in its downwards-linked scopes;
• In a classifier declaration scope (including object and companion object declarations), the declared object is available as implicit this;
• In a classifier declaration scope (including object and companion object declarations), the static callables of the declared object are available on a phantom static implicit this;
• If a function or a property is an extension, this parameter of the extension is also available inside the extension declaration;
• If a lambda expression has an extension function type, this argument of the lambda expression is also available inside the lambda expression declaration.

Important: a phantom static implicit this is a special receiver, which is included in the receiver chain for the purposes of handling static functions from enum classes. It may also be used on platforms to handle their static-like entities, e.g., static methods on JVM platform.

• Receivers provided in the most inner scope have higher priority as ordered w.r.t. link relation;
• The implicit this receiver has higher priority than phantom static implicit this;
• The phantom static implicit this receiver has higher priority than the current class companion object receiver;
• Current class companion object receiver has higher priority than any of the superclass companion objects;
• Superclass companion object receivers are prioritized according to the inheritance order.

Important: these rules mean implicit receivers are always totally ordered w.r.t. their priority, as no two implicit receivers can have the same priority.

Important: DSL-specific annotations (marked with kotlin.DslMarker annotation) change the availability of implicit receivers in the following way: for all types marked with a particular DSL-specific annotation, only the highest priority implicit receiver is available in a given scope.

Note: by definition, local extension callables do not have a dispatch receiver, as they are declared in a statement scope.

Note: there may be situations in which the same implicit receiver is used as both the dispatch receiver and the extension receiver for a particular callable invocation, for example:

interface Y

class X : Y {
    fun Y.foo() {} // `foo` is an extension for Y,
                   //   needs extension receiver to be called

    fun bar() {
        foo() // `this` reference is both
              //   the extension and the dispatch receiver
    }
}

fun <T> mk(): T = TODO()

fun main() {
    val x: X = mk()
    val y: Y = mk()

    // y.foo()
    // Error, as there is no implicit receiver
    //   of type X available

    with (x) {
        y.foo() // OK!
    }
}

The forms of call-expression

• A fully-qualified call without receiver: package.foo();
• A call with an explicit receiver: a.foo();
• An infix function call: a foo b;
• An overloaded operator call: a + b;
• A call without an explicit receiver: foo().

Important: the overload candidates are picked before the most specific function is chosen.

Callables and invoke convention

• Function-like callables:
  • A function named $X$ at its declaration site;
  • A constructor of a type named $X$ at its declaration site;
  • Any of the above named $Y$ at its declaration site, but imported into the current scope using a renaming import as $X$ .
• Property-like callables with an operator function invoke available as a member or an extension in the current scope:
  • A property named $X$ at its declaration site;
  • An object or a companion object named $X$ at its declaration site;
  • A companion object of a classifier type named $X$ at its declaration site;
  • An enum entry named $X$ at its declaration site;
  • Any of the above named $Y$ at its declaration site, but imported into the current scope using a renaming import as $X$ .

• a member function-like callable (including constructors);
• a member property-like callable with a member operator invoke.

• an extension function-like callable;
• a member property-like callable with an extension operator invoke;
• an extension property-like callable with a member operator invoke;
• an extension property-like callable with an extension operator invoke.

Informally: the mnemonic rule to remember this order is “functions before properties, members before extensions”.

c-level partition

• Member function-like callables;
• Member property-like callables.

• Extension function-like callables;
• Member property-like callables with extension invoke;
• Extension property-like callables with member invoke;
• Extension property-like callables with extension invoke.

Building the overload candidate set

Fully-qualified call

Example:

package a.b.c

fun foo(a: Int) {}
fun foo(a: Double) {}
fun foo(a: List<Char>) {}
val foo = {}
. . .
a.b.c.foo()

Here the resulting overload candidate set contains all the callables named foo from the package a.b.c.

Important: a fully-qualified callable name has the form P.n(), where n is a simple callable name and P is a complete package path referencing an existing package.

Call with an explicit receiver

1. f is an accessible member callable of the classifier type type(e) or any of its supertypes;
2. f is an accessible extension callable of the classifier type type(e) or any of its supertypes, including top-level, local and imported extensions.
3. f is an accessible static member callable of the classifier type e.

Important: callables for case 2 include not only regular extension callables, but also extension callables from any of the available implicit receivers. For example, if class P contains a member extension function f for another class T and an object of class P is available as an implicit receiver, extension function f may be used for such call if T conforms to the type type(e).

1. Non-extension member callables named f of type T;
2. Extension callables named f, whose receiver type U conforms to type T, in the current scope and its upwards-linked scopes, ordered by the size of the scope (smallest first), excluding the package scope;
   • First, we assume there is no implicit receiver available for the dispatch receiver of f (i.e., we analyze local extension callables only);
   • Second, we consider each implicit receiver available for the dispatch receiver of f in the order of the implicit receiver priority;
3. Explicitly imported extension callables named f, whose receiver type U conforms to type T;
4. Extension callables named f, whose receiver type U conforms to type T, declared in the package scope;
5. Star-imported extension callables named f, whose receiver type U conforms to type T;
6. Implicitly imported extension callables named f (either from the Kotlin standard library or platform-specific ones), whose receiver type U conforms to type T.

Note: here type U conforms to type T, if $T <: U$ .

Example: when trying to resolve between an explicitly imported extension property (priority 3) with a member invoke (priority 1) and a local property (priority 2) with a star-imported extension invoke (priority 5), the first one wins (max(3, 1) < max(2, 5)).

Important: this means, among other things, that if the set constructed on step $Y$ contains the overall most suitable candidate function, but the set constructed on step $X < Y$ is not empty, the callables from set $X$ will be picked despite them being less suitable overload candidates.

Call with an explicit type receiver

Note: type receivers can appear when working with enum classes or interoperating with platform-dependent code.

1. Static member callables named f of type T;
2. Static member callables named f of type T declared implicitly;
3. The overload candidate sets for call T.f(), where T is a companion object of type T.

Call with an explicit super-form receiver

1. Non-extension member callables named f of type A1;
2. Non-extension member callables named f of type A2;
3. …;

14. Non-extension member callables named f of type AN.

1. Non-extension member callables named f of type A.

Infix function call

Important: this filtering is done before we perform selection of the overload candidate set w.r.t. rules for calls with explicit receiver.

Operator call

Important: this filtering is done before we perform selection of the overload candidate set w.r.t. rules for calls with explicit receiver.

Note: this also means that all the properties available through the invoke convention are non-eligible for operator calls, as there is no way of specifying the operator modifier for them; even though the invoke callable is required to always have such modifier. As invoke convention itself is an operator call, it is impossible to use more than one invoke convention in a single call.

Note: these rules are valid not only for dedicated operator expressions, but also for other operator-based defined-by-convention calls, e.g., for-loop iteration conventions, operator-form assignments or property delegation.

Call without an explicit receiver

Note: this case does not include calls using the invoke operator function where the left-land side of the call is not an identifier, but some other kind of expression (as this is not a simple path). These cases are handled the same way as operator calls and need no further special treatment.

Example:

fun foo(a: Foo, b: Bar) {
    (a + b)(42)
    // Such a call is handled as if it is
    //   (a + b).invoke(42)
}

1. Local non-extension callables named f in the current scope and its upwards-linked scopes, ordered by the size of the scope (smallest first), excluding the package scope;
2. The overload candidate sets for each pair of implicit receivers e and d available in the current scope, calculated as if e is the explicit receiver, in order of the receiver priority;
3. Top-level non-extension functions named f, in the order of:
   1. Callables explicitly imported into the current file;
   2. Callables declared in the same package;
   3. Callables star-imported into the current file;
   4. Implicitly imported callables (either from the Kotlin standard library or platform-specific ones).

Call with named parameters

Important: this filtering is done before we perform selection of the overload candidate set w.r.t. rules for the respective type of call.

Note: for properties called via invoke convention, the named parameters must be present in the declaration of the invoke operator function.

Call with trailing lambda expressions

Example: this means that calls f(1, 2) { g() } and f(1, 2, body = { g() }) are completely equivalent w.r.t. the overload resolution, assuming body is the name of the last formal parameter of f.

Call with specified type parameters

Important: this filtering is done before we perform selection of the overload candidate set w.r.t. rules for the respective type of call.

Determining function applicability for a specific call

Rationale

Description

• For every non-lambda argument inferred to have type $T_i$ , corresponding to the function parameter of type $U_j$ , a constraint $T_i <: U_j$ is constructed;
• All declaration-site type constraints for the function are also added to the constraint system;
• For every lambda argument with the number of lambda arguments known to be $K$ , corresponding to the function parameter of type $U_m$ , a special constraint of the form $\left(\operatorname{\text{FT}}(L_1, \ldots, L_K) \rightarrow R \mathbin{\operatorname{\&}}\operatorname{\text{FTR}}(\operatorname{\text{RT}}, L_1, \ldots, L_n) \rightarrow R\right) <: U_m$ is added to the constraint system, where $R, \operatorname{\text{RT}}, L_1, \ldots, L_K$ are fresh type variables;
• For each lambda argument with an unknown number of lambda arguments (that is, being equal to 0 or 1), corresponding to the function parameter of type $U_n$ , a special constraint of the form $\left(\operatorname{\text{FT}}() \rightarrow R \mathbin{\operatorname{\&}}\operatorname{\text{FT}}(L) \rightarrow R \mathbin{\operatorname{\&}}\operatorname{\text{FTR}}(\operatorname{\text{RT}}) \rightarrow R \mathbin{\operatorname{\&}}\operatorname{\text{FTR}}(\operatorname{\text{RT}}, L) \rightarrow R\right) <: U_m$ is added to the constraint system, where $R, \operatorname{\text{RT}}, L$ are fresh type variables;

Note: although it is impossible to create a value of type $\operatorname{\texttt{kotlin.Nothing}}$ directly, there may be situations where performing overload resolution on such value is necessary; for example, it may occur when doing safe navigation on values of type $\operatorname{\texttt{kotlin.Nothing?}}$ .

Choosing the most specific candidate from the overload candidate set

Rationale

The most specific callable can forward itself to any other callable from the overload candidate set, while the opposite is not true.

fun f(arg: Int, arg2: String) {}        // (1)
fun f(arg: Any?, arg2: CharSequence) {} // (2)
...
f(2, "Hello")

fun f1(arg: Int, arg2: String) {
    f2(arg, arg2) // VALID: can forward both arguments
}
fun f2(arg: Any?, arg2: CharSequence) {
    f1(arg, arg2) // INVALID: function f1 is not applicable
}

Algorithm of MSC selection

• For every non-default argument of the call and their corresponding declaration-site parameter types $X_1, \ldots, X_N$ of $F_1$ and $Y_1, \ldots, Y_N$ of $F_2$ , a type constraint $X_K <: Y_K$ is built unless both $X_K$ and $Y_K$ are built-in integer types. If both $X_K$ and $Y_K$ are built-in integer types, a type constraint $\operatorname{\text{Widen}}(X_K) <: \operatorname{\text{Widen}}(Y_K)$ is built instead, where $\operatorname{\text{Widen}}$ is the integer type widening operator. During construction of these constraints, all declaration-site type parameters $T_1, \ldots, T_M$ of $F_1$ are considered bound to fresh type variables $T^{\sim}_1, \ldots, T^{\sim}_M$ , and all type parameters of $F_2$ are considered free;
• If $F_1$ and $F_2$ are extension callables, their extension receivers are also considered non-default arguments of the call, even if implicit, and the corresponding constraints are added to the constraint system as stated above. For non-extension callables, only declaration-site parameters are considered;
• All declaration-site type constraints of $X_1, \ldots, X_N$ and $Y_1, \ldots, Y_N$ are also added to the constraint system.

Note: this constraint system checks whether $F_1$ can forward itself to $F_2$ .

1. Only one of the two candidates is more applicable than the other;
2. Neither of the two candidates is more applicable than the other;
3. Both $F_1$ and $F_2$ are more applicable than the other.

• Any non-parameterized callable is a more specific candidate than any parameterized callable; If there are several non-parameterized candidates, further steps are limited to those candidates.

• Any non-parameterized callable is a more specific candidate than any parameterized callable (same as case 2). If there are several non-parameterized candidates, further steps are limited to those candidates;
• For each candidate we count the number of default parameters not specified in the call (i.e., the number of parameters for which we use the default value). The candidate with the least number of non-specified default parameters is a more specific candidate;
• For all candidates, the candidate having any variable-argument parameters is less specific than any candidate without them.

Note: it may seem strange to process built-in integer types in a way different from other types, but it is needed for cases when the call argument is an integer literal with an integer literal type. In this particular case, several functions with different built-in integer types for the corresponding parameter may be applicable, and the kotlin.Int overload is selected to be the most specific.

Important: compiler implementations may extend these steps with additional checks, if they deem necessary to do so.

Note: unlike the applicability test, the candidate comparison constraint system is not based on the actual call, meaning that, when comparing two candidates, only constraints visible at declaration site apply.

• First, the properties are compared for applicability and the most applicable property is chosen as described above. If several properties are equally applicable, this is an overload ambiguity as usual;
• Second, for the property selected at first step, the most applicable operator invoke overload is chosen.

Using lambda return type to refine function applicability

1. We check if the function call contains exactly one lambda argument $A$ which requires type inference (which does not have an explicitly defined type).

2. For every function in $C$ we collect parameters $P_i$ corresponding to argument $A$ and check their function types $T_i$ to be structurally equal excluding return types (SEERT).

Informally: SEERT checks whether function types have the exactly same input parameters.

Examples: the following two function types are considered SEERT.

• (Int, String) -> Int
• (Int, String) -> Double

The following two function types are not considered SEERT.

• Int.(String) -> Int
• (Int, String) -> Double

Note: If any of the checks described above fails, we continue with the set $C^\prime = C$ .

Example:

@OverloadResolutionByLambdaReturnType
fun foo(cb: (Unit) -> String) = Unit // (1)

@OverloadResolutionByLambdaReturnType
fun foo(cb: (Unit) -> Int) = Unit // (2)

fun testOk01() {
    foo { 42 }
    // Both (1) and (2) are applicable
    // (2) is preferred by the lambda return type
}

Example:

@OverloadResolutionByLambdaReturnType
fun foo(cb: Unit.() -> String) = Unit // (1)

@OverloadResolutionByLambdaReturnType
fun foo(cb: (Unit) -> Int) = Unit // (2)

fun testError01() {
    val take = Unit
    // Overload ambiguity
    foo { 42 }
    // Both (1) and (2) are applicable
    // None is preferred by the lambda return type
    //   as their parameters are not SEERT
}

Example:

@OverloadResolutionByLambdaReturnType
fun foo(cb: Unit.() -> String) = Unit // (1)

@OverloadResolutionByLambdaReturnType
fun foo(cb: (Unit) -> Int) = Unit // (2)

fun testOk02() {
    val take = Unit
    foo { a -> 42 }
    // Only (2) is applicable
    //   as its lambda takes one parameter
}

Example:

@OverloadResolutionByLambdaReturnType
fun foo(cb: (Unit) -> String) = Unit // (1)

@OverloadResolutionByLambdaReturnType
fun foo(cb: (Unit) -> CharSequence) = Unit // (2)

fun testError02() {
    // Error: required String, found CharSequence
    foo { a ->
        val a: CharSequence = "42"
        a
    }
    // Both (1) and (2) are applicable
    // (1) is the only most specific candidate
    //   We do not attempt refinement by the lambda return type
}

Resolving property access

Important: this section concerns only properties accessed using property access syntax a.x or just x without call suffix. If a property is accessed with a call suffix, it is treated as any other callable and is required to have a suitable invoke overload available, see the rest of this part for details

Note: there is also safe navigation syntax for both assignment and read-only access, but that is expanded to non-safe navigation syntax covered by this section. Please refer to corresponding sections for details.

Example: one may consider property access in class A to be resolved as if it has been transformed to class AA.

class A {
    val a: Int = 5 // (1)

    val Double.a: Boolean // (2)
        get() = this != 42.0

    fun test() {

        println(a) // Resolves to (1)

        with(42.0) {
            println(this@A.a) // Resolves to (1)
            println(this.a) // Resolves to (2)
            println(a) // Resolves to (2)
        }
    }
}

class AA {
    fun a$get(): Int = 5 // (1)

    fun Double.a$get(): Boolean // (2)
              = this != 42.0

    fun test() {

        println(a$get()) // Resolves to (1)

        with(42.0) {
            println(this@AA.a$get()) // Resolves to (1)
            println(this.a$get()) // Resolves to (2)
            println(a$get()) // Resolves to (2)
        }
    }
}

Note: informally, one may look at property assignment resolution as a sub-kind of read-only property resolution described above, first resolving the property as if it was accessed in a read-only fashion, and then using the setter. Read-only property access and property assignment syntax used in the same position never resolve to different property candidates

Example: one may consider property access in class B to be resolved as if it has been transformed to class BB. Declaration bodies for ephemeral functions are omitted to avoid confusion

class B {
    var b: Int = 5 // (1)

    val Double.b: Int // (2)
        get() = this.toInt()

    fun test() {
        b = 5 // Resolves to (1)

        with(42.0) {
            // Resolves to (1)
            this@B.b = 5 
            // Resolves to (2) and compiler error: cannot assign read-only property
            this.b = 5 
            // Resolves to (2) and compiler error: cannot assign read-only property
            b = 5 
        }
    }
}

class BB {
    fun b$get(): Int // (1, getter)
    fun b$set(value: Int) // (1, setter)

    fun Double.b$get(): Int // (2, getter)
    fun Double.b$set(value: Int) // (2, setter)

    fun test() {
        b$set(5) // Resolves to (1)

        with(42.0) {
            // Resolves to (1)
            this@B.b$set(5) 
            // Resolves to (2)
            this.b$set(5) 
            // Resolves to (2)
            this.b$set(5) 
        }
    }
}

• Properties without getter or setter are assumed to have default implementations for accessors (ones which get or set its backing field);
• The overload resolution takes into account the kind of property, meaning an extension read-only property is considered to have an extension getter, an extension mutable property is considered to have an extension getter and setter, etc.;
• Object declarations and enumeration entries may be accessed using the property access syntax given that they may be resolved in the current scope.

Resolving callable references

Resolving callable references not used as arguments to a call

• For each callable reference candidate, we perform the following steps:
  • We build its type constraints and add them to the constraint system of the expression the callable reference is used in;
  • A callable reference is deemed applicable if the constraint system is sound;
• For all applicable candidates, the resolution sets are built according to the same rules as building OCS for regular calls;
• If the highest priority set contains more than one callable, this is an overload ambiguity and should be reported as a compile-time error.
• Otherwise, the single callable in the set is chosen as the result of the resolution process.

Note: this is different from the overload resolution for regular calls in that no most specific candidate selection process is performed inside the sets

Important: when the callable reference resolution for T::f requires building overload candidate sets for both type and value receiver candidates, they are considered in the following order.

1. Static member callables named f of type T;
2. The overload candidate sets for call t::f, where t is a value of type T;
3. The overload candidate sets for call T::f, where T is a companion object of type T.

Callable references to members of companion objects are deprioritized, as you could always use the T.Companion::f syntax to reference them.

Important: when building the OCS for a callable reference, invoke operator convention does not apply, and all property references are treated equally as function references, being placed in the same sets. For example, consider the following code:

fun foo() = 1
val foo = 2
...
val y = ::foo

Here both function foo and property foo are valid candidates for the callable reference and are placed in the same candidate set, thus producing an overload ambiguity. It is not important whether there is a suitable invoke operator available for the type of property foo.

Example: consider the following two functions:

fun foo(i: Int): Int = 2         // (1)
fun foo(d: Double): Double = 2.0 // (2)

In the following case:

val x: (Int) -> Int = ::foo

candidate (1) is picked, because (assuming $\operatorname{CRT}$ is the type of the callable reference) the constraint $\operatorname{CRT} <: \operatorname{\text{FT}}(\operatorname{\texttt{kotlin.Int}}) \rightarrow \operatorname{\texttt{kotlin.Int}}$ is built and only candidate (1) is applicable w.r.t. this constraint.

In another case:

fun bar(f: (Double) -> Double) {}

bar(::foo)

candidate (2) is picked, because (assuming $\operatorname{CRT}$ is the type of the callable reference) the constraint $\operatorname{CRT} <: \operatorname{\text{FT}}(\operatorname{\texttt{kotlin.Double}}) \rightarrow \operatorname{\texttt{kotlin.Double}}$ is built and only candidate (2) is applicable w.r.t. this constraint.

Please note that no bidirectional resolution is performed here as there is only one candidate for bar. If there were more than one candidate, the bidirectional resolution process would apply, possibly resulting in an overload resolution failure.

Bidirectional resolution for callable calls

1. For each overload candidate f, a separate overload resolution process is completed as described in other parts of this section, up to the point of picking the most specific candidate. During this process, the only constraint for the callable reference ::g is that it is an argument of a function type;
2. For the most specific candidate f found during the previous step, the overload resolution process for ::g is performed as described here and the most specific candidate for ::g is selected.

Note: this may result in selecting the most specific candidate for f which has no available candidates for ::g, meaning the bidirectional resolution process fails when resolving ::g.

Type inference and overload resolution

Note: if we had allowed interdependence between type inference and overload resolution, we would have been able to create an infinitely oscillating behaviour, leading to an infinite compilation.

Important: an exception to this limitation is when a lambda return type is used to refine function applicability. By limiting the scope of interdependence between type inference and overload resolution to a single step, we avoid creating an oscillating behaviour.

Conflicting overloads

• f is not overriding g (and vice versa);
• f and g belong to the same level of c-level partition;
• f and g are declared in the same scope.