Lambda expressions

What it is and why it exists

A lambda expression is a function literal written inside braces. It has no declared name, but it produces a value that can be invoked. Kotlin treats functions as first-class functions , so you can store that value in properties and collections, pass it as an argument, or return it from another function.

A function type describes the value’s calling contract. (Order) -> Boolean accepts an Order and returns a Boolean, () -> Unit accepts no arguments and produces only an effect, and suspend (Request) -> Response represents a suspending call. Static types let higher-order functions accept behavior while the compiler checks inputs and results.

Lambdas solve the problem of handing behavior to other code. Collection operations use them for filtering and transformation rules, event APIs retain them as callbacks, resource functions wrap controlled operations in them, and builders use them for local configuration syntax. When behavior is used once or sits next to its call site, a lambda is often more compact than a separate function declaration.

A lambda does not automatically make a function pure, evaluation lazy, execution thread-safe, or code faster. It is only one way to write a function value; the receiving API decides whether to invoke it immediately, how many times to invoke it, which thread to use, whether to retain it, and where exceptions go. At a call site, the function parameter’s contract matters more than the braces.

How it works

Function types define the call shape

An ordinary function type has the form (P1, P2) -> R. Parameter types sit to the left of the arrow and the result type sits to the right; parameter names may appear in the type to improve readability and IDE hints, but they do not affect type compatibility. A nullable function type needs parentheses, as in ((String) -> Int)?, which differs from (String) -> Int?, a function returning a nullable value.

A function type with receiver adds the receiver before the parameter list, as in ReceiptBuilder.() -> Unit. Invoking such a value requires a ReceiptBuilder; inside the lambda, that object becomes the implicit this. A suspending function type carries suspend and can run only in a context that permits suspension.

Common shapes are:

Function parameters are contravariant and results are covariant. A function that handles any Number and returns String can be used where code will pass only Int and requires only Any. To judge compatibility, ask whether the candidate can accept every value the caller may send and whether its result meets the type the caller promises.

Expected types drive inference

The full lambda shape is { parameters -> body }, and the last expression becomes the result. When an assignment target or function parameter supplies an expected type, parameter types can usually be omitted. With one inferable parameter, you can also omit the parameter list and arrow and use the implicit name it.

Inference needs context. Written alone, { value -> value.length } does not tell the compiler what value is; assigning it to (String) -> Int or passing it to a parameter with a known type establishes String. When overloads offer more than one expected type, add a variable type, parameter type, or named argument to narrow resolution.

Lambdas, anonymous functions, and function references can all produce function-type values. ::parseRecord refers to an existing function, parser::parse binds a receiver to a particular object, and Record::id can pass a property read as a function. A function reference preserves a useful name when an existing declaration already states the intent; a lambda is more direct when it must capture local configuration or combine a few operations.

Invocation and trailing lambdas

A function value can run through ordinary call syntax, predicate(order), or explicitly as predicate.invoke(order). The first form reads like an ordinary function and is usually clearer. The caller cannot tell from this syntax whether the implementation came from a lambda, anonymous function, function reference, or another value implementing the calling convention.

When a function’s last parameter has a function type, its lambda argument can move outside the parentheses. This is a trailing lambda. If it is the only argument, the parentheses can disappear too. The rule changes only call syntax; it does not change parameter order or turn arbitrary braces into an asynchronous task or a new language construct.

The trailing position always corresponds to the last parameter. If an API has several function parameters with defaults, load { handle() } may bind the last failure callback rather than the earlier success callback. Use named arguments in such calls so each callback’s role remains visible in source.

Capture creates a closure

A lambda can access local variables visible where it is defined. The function value and those outer bindings form a closure . Kotlin lets a lambda read and modify a captured var, so multiple lambdas created in one scope may share one changing piece of state.

Capture is not a concurrency primitive. If several threads invoke the same closure, reads and writes of an ordinary var do not become atomic and gain no automatic visibility guarantee. When a callback is retained across threads, protect state with locks, atomic types, message passing, or single-thread ownership rather than relying on the lambda’s compact appearance.

A retained lambda also extends the reachability of objects it captures. A listener that needs only a request ID but captures the entire request context can retain caches, buffers, or service references with it. Extracting the small stable value first and then creating the long-lived callback makes the lifetime boundary clearer.

Receivers and SAMs are different contracts

A lambda with receiver makes an object the implicit this, which suits hierarchical construction or a group of operations on a constrained object. It remains an ordinary function value; it does not add a parser or automatically restrict nested receivers. Scope control for a complex DSL belongs to @DslMarker and deliberate DSL design.

A functional interface is declared with fun interface and has one abstract method. SAM conversion converts a matching lambda into an instance of that nominal interface; Kotlin/JVM also supports Java single-abstract-method interfaces. An interface can have a name, non-abstract members, and its own extensions, while a plain function type expresses only inputs and a result.

If an API only needs to invoke behavior, prefer a function type and introduce a typealias when a domain name helps. If callers must promise a nominal domain role or the contract needs other members, a fun interface is a better fit. Both can accept lambda syntax, but they are not interchangeable API boundaries.

Examples

The four programs below demonstrate function types, closure state, receivers, and return control. Each is a standalone file compiled with Kotlin 2.4.10 and run on JRE 21; every following output block comes from that execution.

Passing a filtering rule as a value

The first program declares an explicit predicate type and uses the same higher-order function with both a lambda variable and a trailing lambda. Order::id supplies a property reference as the mapping function.

selectIds decides when and for which elements to invoke the predicate; the lambda supplies only the decision rule. The first call places a function value inside the parentheses, while the second moves the final lambda outside. Both pass the same (Order) -> Boolean contract.

The property reference Order::id has a shape you can view as (Order) -> String. It accepts an unbound Order and returns that instance’s id. In contrast, orders.first()::id would be a bound property reference and would no longer need an Order argument.

Each factory call owns separate state

The second program returns a function that captures next. Two calls to ticketSequence create two states, while adding an alias for one function value does not copy its state.

fun ticketSequence(prefix: String): () -> String {
    var next = 1
    return { "$prefix-${next++}" }
}

fun main() {
    val web = ticketSequence("WEB")
    val batch = ticketSequence("BATCH")

    println(listOf(web(), web(), batch(), web(), batch()))

    // The alias still points to the same closure.
    val sameWeb = web
    println(sameWeb())
}

[WEB-1, WEB-2, BATCH-1, WEB-3, BATCH-2]
WEB-4

web and batch come from separate factory calls, so each begins at 1. sameWeb only copies the function-value reference; its call produces WEB-4, showing that it operates on the same captured state as web.

This small state machine fits an interface with only one operation. If state needs reset, inspection, persistence, or concurrency control, a class with explicit methods and ownership is usually easier to maintain. A function value hides the representation of state; it does not eliminate state design.

Constraining configuration vocabulary with a receiver

The third program accepts ReceiptBuilder.() -> Unit. Calls to item inside the block resolve against the implicit ReceiptBuilder receiver, while the entry function creates the builder, invokes the block, and builds the result.

class ReceiptBuilder {
    private val lines = mutableListOf<String>()

    fun item(name: String, cents: Int) {
        require(name.isNotBlank()) { "name must not be blank" }
        require(cents > 0) { "cents must be positive" }
        lines += "$name=${cents}c"
    }

    fun build(): String = lines.joinToString("|")
}

fun receipt(block: ReceiptBuilder.() -> Unit): String {
    val builder = ReceiptBuilder()
    builder.block()
    return builder.build()
}

fun main() {
    val summary = receipt {
        item("coffee", 450)
        item("cake", 325)
    }

    println(summary)
}

coffee=450c|cake=325c

builder.block() does two things: it invokes the function value and supplies builder as its receiver. You can also invoke a receiver function value as block(builder), but the dotted form makes the receiver relationship more visible.

The concise calls inside the block come from its static receiver type, not arbitrary name lookup. Every public ReceiptBuilder member becomes vocabulary in the block, so a builder should keep a narrow surface and finish validation and ownership conversion before returning its final result.

Separating non-local and labeled returns

The fourth program shows two targets. The bare return passed to inline forEach returns from firstReady; return@transform ends only the current mapNotNull invocation.

fun firstReady(records: List<String>): String? {
    records.forEach { record ->
        if (record.startsWith("ready:")) {
            // forEach is inline, so this returns from firstReady.
            return record.removePrefix("ready:").trim()
        }
    }
    return null
}

fun normalized(records: List<String>): List<String> =
    records.mapNotNull transform@{ record ->
        val value = record.substringAfter(':', missingDelimiterValue = "")
        // The labeled return skips only the current element.
        if (value.isBlank()) return@transform null
        value.trim().uppercase()
    }

fun main() {
    val records = listOf("skip", "ready: alpha", "ready: beta", "bad:")

    println(firstReady(records))
    println(normalized(records))
}

alpha
[ALPHA, BETA]

The bare return can cross forEach because the standard library inlines this lambda at the call site. Passing the same lambda to an ordinary non-inline function would fail to compile; the compiler cannot let a retained or indirectly called callback return from a call frame that no longer exists.

The target of return@transform null comes from its explicit label. The implicit call-name label return@mapNotNull also works, but an explicit label is easier to review around nested or same-named calls. If the only need is to stop traversal early, an ordinary for loop is often the most direct form.

Pitfalls

Fix: First determine whether the receiving function is inline and whether the lambda permits non-local return. Use return@label to end only this lambda call, an anonymous function for more involved local return logic, or an ordinary loop to stop traversal. Do not infer control flow just because forEach looks like a loop.

Fix: Name parameters as soon as lambdas nest, such as order and lineItem. Reserve it for a one-parameter, one-expression body with an obvious meaning. During review, annotate the static type of each name instead of guessing its referent from property names.

Fix: Call a factory once per owner for independent state, copy an immutable per-iteration value when you need a snapshot, and define synchronization when sharing across threads is intentional. Verify ownership with interleaved and concurrent tests, not one isolated call to each callback.

Fix: Use named arguments for callbacks with different roles, such as onSuccess = { ... } and onFailure = { ... }. When designing a new API, avoid distinguishing several same-shaped callbacks only by position; nominal interfaces or event objects can put meaning into names and types.

Fix: Use a function type for only a call shape; a typealias adds a name but no new type; use a functional interface when nominal identity or additional members matter. Before changing a public API, compile both Kotlin and Java consumers instead of checking only that lambda syntax remains short.

Further reading

These links point to source files for Kotlin’s official documentation. They cover function types and lambda syntax, inlining and non-local control flow, functional interfaces and SAM conversion, and function references.

• Kotlin higher-order functions and lambdas documentation source
• Kotlin inline functions documentation source
• Kotlin functional interfaces documentation source
• Kotlin callable references documentation source