Extension functions and scope functions

Adding to something you do not own

Suppose you keep needing shouty text. The obvious move:

1fun shout(text: String): String {
2  return text.uppercase() + "!"
3}

Call it with shout("hello") and you get HELLO!. Fine. But now compare how it reads next to Kotlin's own functions:

println(shout("hello".trim().lowercase()))

The reading order has gone inside out. trim and lowercase flow left to right; shout wraps around the outside, so your eye has to go out to the front and back again.

You cannot open up Kotlin's String and add a shout to it — it is not your code. What you can do is write a function that behaves exactly as though you had.

Extension functions

1fun String.shout(): String {
2  return uppercase() + "!"
3}

Now "hello".shout() prints HELLO!. The only new thing is String. in front of the function name.

The type in front is the receiver — the thing the function will be called on. Inside the body, this refers to it, and as usual you may leave this out, which is why uppercase() on its own works.

Now the reading order is fixed:

println("hello".trim().lowercase().shout())

Left to right, one step after another, with yours indistinguishable from Kotlin's.

Extensions work on any type, including your own and including Int:

fun Int.isEven(): Boolean = this % 2 == 0

After that line, 4.isEven() is true and 7.isEven() is false.

What is really happening

No magic, and worth knowing: the compiler turns "hello".shout() into an ordinary function call, shout("hello"). Nothing is added to String — the dot is a convenience, decided at compile time.

Two consequences follow directly:

• An extension cannot see private parts of the type it extends. It is outside code, and stays outside.
• If the type already has a real function with that name and shape, the real one wins.

You have been using extensions all along without knowing it. filter, map, sumOf and toSet from Lessons 1.11 and 1.12 are all extension functions on collections, living in Kotlin's standard library rather than inside List itself.

The five scope functions

A scope function does one small thing: it hands you a block of code that already has one object in scope, so you can do several things with it without repeating its name.

There are exactly five, and they differ in only two ways: what the object is called inside the block, and what comes back out.

That table is the entire feature. Two of the five are worth learning properly today.

apply — set several things up

1val r = Robot().apply {
2  name = "Bolt"
3  power = 9
4}

Inside the braces you are "in" the robot, so you can name its properties directly with no r. in front. And because apply hands the object back, the whole thing is still an expression you can assign. Compare it with the long way:

1val r = Robot()
2r.name = "Bolt"
3r.power = 9

Same result. apply is tidier and, more importantly, keeps the setup visibly attached to the thing being set up.

let — do something with a value, especially a nullable one

1val nick: String? = null
2nick?.let {
3  println(it.shout())
4}

Read the two symbols together. The ?. means only if this is not null, and let means run this block with the value as it. Put them side by side and you get the cleanest way in Kotlin to say "do all of this, but only if there is something there".

With nick = null, the block simply does not run. Nothing is printed and nothing crashes.

let also hands back whatever the block produced, so it can sit in the middle of a chain:

val len = nick?.let { it.length } ?: 0

The other three, briefly

also is for a step on the side — logging, checking — because it hands the object straight through unchanged: list.also { println(it.size) }. run and with are let and apply's cousins that use this instead of it; you will meet them in real code and can look them up in the table then.

1HELLO!
2BOLT AT 9!
3done