Kotlin language specification

Statements

Example: Kotlin supports using conditionals both as expressions and as statements. As their use as expressions is more general, detailed information about conditionals is available in the Expressions section of the specification.

Assignments

• An identifier referring to a mutable property;
• A navigation expression referring to a mutable property. If this navigation operator is the safe navigation operator, this introduces a special case of safe assignment;
• An indexing expression.

Note: Kotlin assignments are not expressions and cannot be used as such.

Simple assignments

• If a property has a setter (including delegated properties), it is called using the right-hand side expression as its argument;
• Otherwise, if a property is a mutable property, its value is changed to the evaluation result of the right-hand side expression.

Operator assignments

• $A\ \texttt{+=}\ B$ is exactly the same as one of the following:
  • $A\texttt{.plusAssign(}B\texttt{)}$ if a suitable plusAssign operator function exists and is available;
  • $A\ \texttt{=}\ A\texttt{.plus(}B\texttt{)}$ if a suitable plus operator function exists and is available.
• $A\ \texttt{-=}\ B$ is exactly the same as one of the following:
  • $A\texttt{.minusAssign(}B\texttt{)}$ if a suitable minusAssign operator function exists and is available;
  • $A\ \texttt{=}\ A\texttt{.minus(}B\texttt{)}$ if a suitable minus operator function exists and is available.
• $A\ \texttt{*=}\ B$ is exactly the same as one of the following:
  • $A\texttt{.timesAssign(}B\texttt{)}$ if a suitable timesAssign operator function exists and is available;
  • $A\ \texttt{=}\ A\texttt{.times(}B\texttt{)}$ if a suitable times operator function exists and is available.
• $A\ \texttt{/=}\ B$ is exactly the same as one of the following:
  • $A\texttt{.divAssign(}B\texttt{)}$ if a suitable divAssign operator function exists and is available;
  • $A\ \texttt{=}\ A\texttt{.div(}B\texttt{)}$ if a suitable div operator function exists and is available;
• $A\ \texttt{\%=}\ B$ is exactly the same as one of the following:
  • $A\texttt{.remAssign(}B\texttt{)}$ if a suitable remAssign operator function exists and is available;
  • $A\ \texttt{=}\ A\texttt{.rem(}B\texttt{)}$ if a suitable rem operator function exists and is available.

Note: before Kotlin version 1.3, there were additional overloadable functions for % called mod/modAssign

Example: consider the following compound operator statement: x[y] += z. The corresponding expansion variants are x.get(y).plusAssign(z) and x.set(x.get(y).plus(z)) according to expansion rules for corresponding operators. If, for example, the call to set in the second variant results in resolution or inference error, the whole corresponding expansion is deemed unresolved and the first variant is picked if applicable.

Note: although for most real-world use cases operators ++ and -- are similar to operator assignments, in Kotlin they are expressions and are described in the corresponding section of this specification.

Safe assignments

• a?.c is exactly the same as

  when(val $tmp = a) {
      null -> null
      else -> { $tmp.c }
  }

  For any right-hand combinations of operators present in c, which are expanded further, as usual.

Example: The assignment

x?.y[0] = z

is expanded to

when(val $tmp = x) {
    null -> null
    else -> { $tmp.y[0] = z }
}

which, according to expansion rules for indexing assignments is, in turn, expanded to

when(val $tmp = x) {
    null -> null
    else -> { $tmp.y.set(0, z) }
}

Loop statements

While-loop statements

Note: this also means that the condition expression is evaluated before every evaluation of the body, including the first one.

Do-while-loop statements

Note: this also means that the body is always evaluated at least once.

For-loop statements

Note: unlike most other languages, Kotlin does not have a free-form condition-based for loops. The only form of a for-loop available in Kotlin is the “foreach” loop, which iterates over lists, arrays and other data structures.

when(val $iterator = C.iterator()) {
    else -> while ($iterator.hasNext()) {
                val VarDecl = __iterator.next()
                <... all the statements from Body>
            }
}

Note: the expansion is hygienic, i.e., the generated iterator variable never clashes with any other variable in the program and cannot be accessed outside the expansion.

Code blocks

Note: Kotlin does not support code blocks as statements; a curly-braces code block in a statement position is a lambda literal.

Informally: you may consider the case of a missing last expression as if a synthetic last expression with no runtime semantics and type kotlin.Unit is introduced in its place.

Note: this is equivalent to wrapping the single expression in a new synthetic code block.

• the value of its last expression if it exists;
• the singleton kotlin.Unit object otherwise.

Coercion to kotlin.Unit

Examples:

fun foo() {
    val a /* : () -> Unit */ = {
        if (true) 42
        // CSB with no last expression
        // Type is defined to be `kotlin.Unit`
    }

    val b: () -> Unit = {
        if (true) 42 else -42
        // CSB with last expression of type `kotlin.Int`
        // Type is expected to be `kotlin.Unit`
        // Coercion to kotlin.Unit applied
    }
}