← Back to Kotlin Course | Chapter 3: Control Flow | Lesson 7 of 7

Return with Labels

A labeled return lets you jump out of just one specific inner block, like a lambda, instead of leaving the whole function.

In this page:

  1. Non-Local Return from a Lambda
  2. Returning from the Lambda Only
  3. Explicit Labels on a Lambda
  4. Choosing Local vs Non-Local Return
Syntax
kotlin 
collection.forEach {
    return@forEach          // return from the lambda only
}

collection.forEach label@{
    return@label
}

Non-Local Return from a Lambda

A plain return inside a lambda passed to an inline function like forEach does not just skip that one iteration -- it exits the entire enclosing function immediately.

Example: Non-Local Return from a Lambda

markup 
// Define the function `findFirstEven` taking `numbers` and returning a `Int?`
fun findFirstEven(numbers: List<Int>): Int? {
    numbers.forEach {
        if (it % 2 == 0) return it
    }
    // Return `null` from this function
    return null
}

// Entry point: execution of the program starts here
fun main() {
    // Print "First even: ${findFirstEven(listOf(1, 3, 4, 5))}" to the console, with a trailing newline
    println("First even: ${findFirstEven(listOf(1, 3, 4, 5))}")
}

Returning from the Lambda Only

Using the implicit label named after the function the lambda is passed to, such as return@forEach, returns from just that single lambda invocation and lets the loop continue with the next item.

Example: Returning from the Lambda Only

markup 
// Entry point: execution of the program starts here
fun main() {
    // Declare a read-only variable `numbers`, set to `listOf(1, 2, 3, 4, 5)`
    val numbers = listOf(1, 2, 3, 4, 5)
    numbers.forEach {
        if (it % 2 == 0) return@forEach
        // Print "Odd: $it" to the console, with a trailing newline
        println("Odd: $it")
    }
}

Explicit Labels on a Lambda

You can also define your own explicit label before a lambda, like myLoop@ { ... }, and return from it specifically using return@myLoop.

Example: Explicit Labels on a Lambda

markup 
// Entry point: execution of the program starts here
fun main() {
    // Declare a read-only variable `numbers`, set to `listOf(1, 2, 3, 4, 5)`
    val numbers = listOf(1, 2, 3, 4, 5)
    numbers.forEach myLoop@{
        if (it == 3) return@myLoop
        // Print "Value: $it" to the console, with a trailing newline
        println("Value: $it")
    }
}

Choosing Local vs Non-Local Return

Deciding whether a return inside a lambda should exit the whole function or just that lambda invocation is a deliberate choice -- use the labeled form whenever only the lambda should stop.

Example: Choosing Local vs Non-Local Return

markup 
// Define the function `processAll` taking `numbers`
fun processAll(numbers: List<Int>) {
    // Loop over `numbers`, binding each item to `n`
    for (n in numbers) {
        numbers.forEach {
            if (it == n) return@forEach
            // Print "Comparing $n with $it" to the console, with a trailing newline
            println("Comparing $n with $it")
        }
    }
}

// Entry point: execution of the program starts here
fun main() {
    processAll(listOf(1, 2))
}
Related Topics

break, continue, and Labels · Ranges · while and do-while Loops · for Loops

{# common_mistakes/chapter_summary/browser_support: on Hindi pages the view already swaps in the hi_ translation fields (or blanks these out if untranslated), so this renders correctly for both languages without a lang_code check here. #}
Common Mistakes
  1. Assuming a plain return inside a lambda passed to forEach exits only that lambda, when it actually returns from the enclosing function (a non-local return).
  2. Forgetting to label the return when only the lambda itself should stop, resulting in the surrounding function exiting unexpectedly early.
  3. Using implicit labels (named after the function, like forEach$0) instead of the clearer explicit label syntax when precision matters.
Chapter Summary
  • A plain return inside a lambda passed to an inline function performs a non-local return, exiting the enclosing function entirely.
  • Labeling a lambda with name@ { ... } and using return@name returns from just that lambda, not the whole function.
  • Kotlin also provides an implicit label matching the name of the function the lambda is passed to, such as return@forEach.
  • Choosing the right kind of return (local vs non-local) avoids surprising control-flow bugs in loops built from higher-order functions.
🔒

Chapter Quiz — Complete all 7 topics to unlock

0/7 topics done

Complete these topics first:

← Previous Lesson break, continue, and Labels Next Lesson → Function Basics

Login to run this code

C/C++/Java/PHP execution requires a free account. Your code is saved — you'll land right back in the editor after logging in.