Labeled Return

A labeled return in Kotlin is a control flow mechanism that explicitly dictates the target scope a return expression exits, enabling local returns from lambda expressions. In Kotlin, an unqualified return always exits the nearest enclosing fun declaration. Consequently, an unqualified return inside a lambda is strictly forbidden and results in a compilation error unless the lambda is passed to an inline higher-order function (which permits a non-local return). Labeled returns address this by explicitly targeting the lambda itself. For non-inline functions, a labeled return provides the only valid way to execute a return statement inside the lambda; for inline functions, it overrides the default non-local return behavior to force a local return.

Explicit Labels

A label is defined by an identifier followed immediately by the @ symbol, placed directly before the lambda expression. The return statement references this label by appending @identifier to the return keyword.

fun explicitLabelSyntax() {
    listOf(1, 2, 3).forEach customLabel@{ 
        if (it == 2) {
            // Exits the lambda marked with 'customLabel@', not the outer function
            return@customLabel 
        }
        println(it)
    }
    println("Outer function continues execution")
}

Implicit Labels

Kotlin automatically generates implicit labels for lambdas passed to higher-order functions. The implicit label shares the exact name of the function to which the lambda is passed. This eliminates the need to declare an explicit label for standard library operations or custom higher-order functions.

fun implicitLabelSyntax() {
    listOf(1, 2, 3).forEach {
        if (it == 2) {
            // Exits the lambda using the implicit 'forEach' label
            return@forEach 
        }
        println(it)
    }
}

Returning Values with Labels

When a lambda requires a return value, the labeled return syntax places the label immediately after the return keyword, followed by a space and the expression to be evaluated and returned to the caller of the lambda.

fun labeledReturnWithValue(): List<String> {
    return listOf(1, 2, 3).map {
        if (it == 2) {
            // Returns the string "Two" to the 'map' function's current iteration
            return@map "Two" 
        }
        it.toString()
    }
}

Interaction with Anonymous Functions

While lambdas require labeled returns to achieve local returns, anonymous functions inherently bind the unqualified return keyword to themselves. Because an anonymous function is declared using the fun keyword, an unqualified return inside it will always exit the anonymous function locally, acting as a structural alternative to labeled returns in lambdas.

fun anonymousFunctionAlternative() {
    listOf(1, 2, 3).forEach(fun(value: Int) {
        if (value == 2) {
            // Exits the anonymous function locally; no label required
            return 
        }
        println(value)
    })
}

Master Kotlin with Deep Grasping Methodology!

Learn More