Kotlin Scope Functions

With this, you can call the object's members directly: name instead of it.name. With it, the object is clearly named, which reads better when you pass it to other functions. Returning the object suits configuration and chaining; returning the result suits calculating something new.

let is most often used with a safe call, to run code only when a value isn't null:

user.email?.let { sendWelcome(it) }
val length = name?.let { it.trim().length } ?: 0

apply configures an object and returns it, which is ideal right after creating something:

val request = Request().apply {
    url = "https://api.example.com/users"
    method = "POST"
    timeoutSeconds = 10
}

Inside apply, properties are set directly, without repeating request. on every line.

also does something extra with an object, such as logging or validating, and passes the object on unchanged:

val user = createUser(form).also { println("Created ${it.id}") }

run and with compute a result from an object's members. run is called on the object (and works with ?.); with takes the object as an argument:

val summary = order.run { "$id: $quantity x $item" }
val area = with(rectangle) { width * height }

takeIf { condition } returns the object if the condition is true, or null if not, which combines well with Elvis: val age = input.toIntOrNull()?.takeIf { it in 0..130 } ?: 0.

• Null check, then use the value: ?.let.
• Set up a new object's properties: apply.
• Add a side effect (log, validate) in a chain: also.
• Calculate a value from an object's members: run or with.

If none of these fits naturally, an ordinary local variable is usually clearer. Avoid nesting scope functions inside each other: two levels of it or this quickly become confusing.

Inside apply, run and with, a bare name is looked up in the nearest scope first. Local variables and function parameters come before the receiver's properties, which catches people out when they share a name:

class Person { var name = ""; var age = 0 }

fun makePerson(name: String, age: Int) = Person().apply {
    this.name = name      // the property gets the parameter
    this.age = age
}

Without this., the line name = name refers to the parameter on both sides, and since parameters are read-only, the compiler stops you with "'val' cannot be reassigned". When the outer variable is a var, there's no error at all: the assignment quietly changes the local variable and the object keeps its old value. Writing this. makes it clear which name you mean. If a block needs this. on most lines, also with a named parameter may read better.

The same naming trick helps with let. Instead of it, give the value a name that says what it is:

email?.let { address -> println("Sending to $address") }

run can also be called without any object. Then it's simply a block that produces a value, which is handy for keeping temporary variables out of the surrounding code:

val total = run {
    val base = 40.0
    val tax = base * 0.25
    base + tax
}                             // 50.0; base and tax don't exist out here

takeUnless is the mirror image of takeIf: it keeps the value when the condition is false. nick.takeUnless { it.isBlank() } ?: "Anonymous" replaces a blank nickname with a default in one line.