Functions & Lambdas

A function starts with fun, then its name, its parameters in parentheses (each written name: Type) and its return type after a colon. Parameters are read-only — you cannot reassign them inside the function. When the whole body is one expression, drop the braces and return and write = expression: a single-expression function. The compiler can infer the return type of a single-expression function; a block body with a result always needs it written.

// Block body: braces, explicit return type, return statement
fun bmi(weightKg: Double, heightM: Double): Double {
    val value = weightKg / (heightM * heightM)
    return value
}

// Single-expression function: return type inferred as Boolean
fun isAdult(age: Int) = age >= 18

fun category(bmi: Double): String = when {
    bmi < 18.5 -> "under"
    bmi < 25.0 -> "normal"
    else -> "over"
}

fun main() {
    val b = bmi(70.0, 1.75)
    println("%.1f".format(b))
    println(category(b))
    println(isAdult(17))
}

22.9
normal
false

fun square(x: Int): Int {
    x * x
}

fun main() {
    println(square(4))
}

Main.kt:3:1: error: missing return statement.

fun square(x: Int): Int = x * x

fun main() {
    println(square(4))
}

A parameter can have a default value, so callers may leave it out. At the call site you can name arguments — greet(name = "Ravi", punctuation = "?") — which lets you skip defaults in the middle and makes calls with several booleans or numbers readable. Together they replace most of the overloads a Java class needs. A vararg parameter accepts any number of values and arrives in the function as an array; to pass an existing array into it, put the spread operator * in front.

fun greet(name: String, greeting: String = "Hello", punctuation: String = "!") =
    "$greeting, $name$punctuation"

fun average(vararg scores: Int): Double =
    if (scores.isEmpty()) 0.0 else scores.sum().toDouble() / scores.size

fun main() {
    println(greet("Asha"))
    println(greet("Asha", "Hi"))
    println(greet("Asha", punctuation = "?"))
    println(greet(punctuation = ".", name = "Ravi"))

    println(average())
    println(average(80, 90))
    val more = intArrayOf(70, 75, 95)
    println(average(60, *more))
}

Hello, Asha!
Hi, Asha!
Hello, Asha?
Hello, Ravi.
0.0
85.0
75.0

fun area(width: Int, height: Int): Int = width * height

fun main() {
    println(area(5))
}

Main.kt:4:13: error: no value passed for parameter 'height'.

fun area(width: Int, height: Int = width): Int = width * height

fun main() {
    println(area(5))
}

A function that returns no useful value returns Unit — Kotlin's version of void, except that it is a real type with a single value, so it works with generics. You never write : Unit or return Unit. Nothing is the type of a function that never returns: it always throws or loops forever. Because Nothing fits anywhere a value is expected, val n = input.toIntOrNull() ?: fail("…") type-checks as an Int. The standard TODO() and error() functions return Nothing.

A local function is declared inside another function. It can read the outer function's parameters and variables, and nothing outside can call it — a clean way to name a repeated step without polluting the file.

fun log(message: String) {          // returns Unit
    println("[log] $message")
}

fun fail(reason: String): Nothing = throw IllegalArgumentException(reason)

fun parseAge(text: String): Int = text.toIntOrNull() ?: fail("not a number: $text")

fun report(name: String, scores: List<Int>) {
    fun line(label: String, value: Any) = println("$name $label: $value")  // local function

    line("count", scores.size)
    line("best", scores.max())
    line("mean", scores.average())
}

fun main() {
    val result = log("starting")
    println(result)                    // the single Unit value

    println(parseAge("42") + 1)
    try {
        parseAge("forty")
    } catch (e: IllegalArgumentException) {
        println("caught: ${e.message}")
    }

    report("Meera", listOf(70, 92, 81))
}

[log] starting
kotlin.Unit
43
caught: not a number: forty
Meera count: 3
Meera best: 92
Meera mean: 81.0

A lambda is a function without a name, written in braces: { a: Int, b: Int -> a + b }. Parameters go before the arrow, the body after it, and the value of the last expression is the result — no return. Every function value has a function type that reads like its signature: (Int, Int) -> Int takes two Ints and returns an Int; () -> Unit takes nothing and returns nothing. When a lambda has exactly one parameter, you may skip declaring it and call it it. To use an existing named function as a value, take a function reference with ::name.

fun isEven(n: Int) = n % 2 == 0

fun main() {
    val add: (Int, Int) -> Int = { a, b -> a + b }
    val shout = { s: String -> s.uppercase() + "!" }
    val double: (Int) -> Int = { it * 2 }      // single parameter: it
    val hello: () -> Unit = { println("hello from a lambda") }

    println(add(2, 3))
    println(shout("hey"))
    println(double(21))
    hello()

    val numbers = listOf(1, 2, 3, 4, 5, 6)
    println(numbers.filter(::isEven))          // function reference
    println(numbers.map(double))
    println(numbers.map { n -> n * n })
    println(numbers.count { it > 3 })
}

5
HEY!
42
hello from a lambda
[2, 4, 6]
[2, 4, 6, 8, 10, 12]
[1, 4, 9, 16, 25, 36]
3

Trailing lambda syntax: if a function's last parameter is a function, you may put the lambda outside the parentheses — numbers.fold(0) { acc, n -> acc + n }. If the lambda is the only argument, the parentheses disappear entirely: numbers.map { it * 2 }. This is why so much Kotlin reads like built-in syntax: repeat(3) { }, thread { } and Compose's Column { } are all ordinary function calls.

fun main() {
    val check = { n: Int ->
        if (n < 0) return
        n * 2
    }
    println(check(3))
}

Main.kt:3:20: error: 'return' is prohibited here.

fun main() {
    val check = { n: Int ->
        if (n < 0) 0 else n * 2
    }
    println(check(3))
}

A higher-order function takes a function as a parameter, returns one, or both. map, filter and forEach are higher-order functions from the standard library; writing your own is no harder. A lambda can read and even modify variables from the scope where it was created — it captures them, forming a closure. A function that returns a lambda can therefore hand out a little piece of private state.

// Takes a function
fun applyTwice(x: Int, f: (Int) -> Int): Int = f(f(x))

// Takes a function and returns a new one
fun logged(name: String, f: (Int) -> Int): (Int) -> Int = { x ->
    val result = f(x)
    println("$name($x) = $result")
    result
}

// Returns a closure that captures its own counter
fun makeCounter(): () -> Int {
    var count = 0
    return { ++count }
}

fun main() {
    println(applyTwice(3) { it * 10 })

    val square = logged("square") { it * it }
    square(4)
    square(9)

    val a = makeCounter()
    val b = makeCounter()
    a(); a()
    println("a=${a()} b=${b()}")
}

300
square(4) = 16
square(9) = 81
a=3 b=1

inline, briefly. Each lambda passed to a normal function becomes an object at runtime. Marking the higher-order function inline makes the compiler paste the function body and the lambda into the call site instead, so no object is allocated. Most standard collection functions are inline. A side effect you will notice: inside a lambda passed to an inline function, a plain return returns from the enclosing function (a non-local return), while return@forEach only ends the current lambda call.

inline fun measure(label: String, block: () -> Unit) {
    println("start $label")
    block()
    println("end $label")
}

fun firstNegative(numbers: List<Int>): Int? {
    numbers.forEach {
        if (it < 0) return it        // non-local: returns from firstNegative
    }
    return null
}

fun main() {
    measure("work") { println("working...") }

    println(firstNegative(listOf(4, -2, 7, -9)))
    println(firstNegative(listOf(1, 2)))

    listOf(1, 2, 3, 4).forEach {
        if (it == 2) return@forEach   // skips just this element
        print("$it ")
    }
    println()
}

start work
working...
end work
-2
null
1 3 4 

A recursive function calls itself on a smaller version of the problem until it reaches a base case that it answers directly. Every call waits on the stack for the one below it, so very deep recursion throws StackOverflowError. When the recursive call is the very last thing the function does — nothing is left to compute after it returns — mark the function tailrec and the compiler rewrites it as a loop that uses no extra stack.

fun sumDigits(n: Int): Int =
    if (n < 10) n                      // base case
    else n % 10 + sumDigits(n / 10)    // smaller problem

// The recursive call is the last operation, so tailrec applies
tailrec fun gcd(a: Int, b: Int): Int =
    if (b == 0) a else gcd(b, a % b)

tailrec fun sumTo(n: Long, acc: Long = 0): Long =
    if (n == 0L) acc else sumTo(n - 1, acc + n)

fun main() {
    println(sumDigits(4096))
    println(gcd(48, 18))
    println(sumTo(1_000_000))   // a million calls deep - fine with tailrec
}

19
6
500000500000

Now that lambdas are familiar, the five scope functions are easy to read: each is a higher-order function that runs a lambda with an object in scope. let and also call the object it; run, with and apply make it this, so you can call its members directly. let, run and with return the lambda's result; apply and also return the object itself. Module 09 compares them in depth.

fun main() {
    // let: transform a value, result = lambda result
    val doubled = "kotlin".let { it.length * 2 }
    println(doubled)

    // apply: configure an object, result = the object
    val sb = StringBuilder().apply {
        append("a")
        append("b")
    }
    println(sb)

    // also: a side effect in the middle of a chain
    val total = listOf(3, 4, 5)
        .also { println("summing $it") }
        .sum()
    println(total)

    // run and with: compute something using this
    println("text".run { uppercase() + length })
    println(with(listOf(1, 2, 3)) { "size=$size first=${first()}" })
}

12
ab
summing [3, 4, 5]
12
TEXT4
size=3 first=1

Single-expression function

fun f(x: Int) = x * 2 — the body is one expression and the return type can be inferred.

Default argument

A parameter value used when the caller leaves the argument out.

Named argument

An argument passed as name = value, in any order.

vararg

A parameter that accepts any number of values; inside the function it is an array. Spread an existing array with *.

Unit

The return type of a function with no useful result; Kotlin's void, with a single value.

Nothing

The type of an expression that never completes normally, such as throw.

Lambda

An anonymous function in braces: { a, b -> a + b }. Its last expression is its result.

Function type

The type of a function value, such as (Int) -> Boolean or () -> Unit.

Higher-order function

A function that takes or returns another function.

Closure

A lambda together with the variables it captured from the scope where it was created.

Trailing lambda

Writing the last function argument outside the parentheses: list.fold(0) { acc, x -> acc + x }.

tailrec

Modifier that turns a tail-recursive function into a loop, so it cannot overflow the stack.