Kotlin Standard Library lambdas

StdlibCheatSheet.kt

@file:Suppress("unused")

import kotlin.*

/*
 * Author:     Laboratory for Electronic and Information Systems (LEIS)
 *             Bojan Potocnik
 *             bojan.potocnik@um.si
 */

/**
 * Explaining Kotlin Standard library lambda functions.
 *
 *  _______________________________________________________________________________________________________
 * | function | "this" |  "it"  | "self." | "return" |  result  | signature                               |
 * |----------|--------|--------|---------|----------|----------|-----------------------------------------|
 * | also     |    -   |  self  |    -    |     -    |   self   | fun <T> T.also(block: (T) -> Unit): T   |
 * | apply    |  self  |    -   |   yes   |     -    |   self   | fun <T> T.apply(block: T.() -> Unit): T |
 * | let      |    -   |  self  |    -    | anything | "return" | fun <T, R> T.let(block: (T) -> R): R    |
 * | run      |  self  |    -   |   yes   | anything | "return" | fun <T, R> T.run(block: T.() -> R): R   |
 * |----------|--------|--------|---------|----------|----------|-----------------------------------------|
 *
 * fun <T, R> with(receiver: T, block: T.() -> R): R
 *  is the same as T.run() but not as an extension function.
 *  "x.run() {}" is the same as "with(x) {}"
 *
 * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/index.html]
 */
@Suppress("UNUSED_VARIABLE", "UNUSED_EXPRESSION")
class StdlibCheatSheet {

    private fun classMember() {}

    /**
     * fun <T> T.also(block: (T) -> Unit): T
     * Calls the specified function *block* with *this* value as its argument and returns *this* value.
     *
     * T.also(): T {
     *     block(T): Unit { it: T ->
     *         ...
     *     }
     *     return T
     * }
     *
     * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/also.html].
     */
    fun also() {
        val argument: String? = "String?"

        val result1: String? = argument.also {
            this                        // StdlibCheatSheet
            this.classMember()
            classMember()

            it                          // argument? (String?)
            val a: Int? = it?.length
            //val b: Int? = length

            // no return (Unit)
        }
        val result2: String? = argument?.also {
            this                        // StdlibCheatSheet
            this.classMember()
            classMember()

            it                          // argument (String)
            val a: Int = it.length
            //val b: Int = length

            // no return (Unit)
        }
    }

    /**
     * fun <T> T.apply(block: T.() -> Unit): T
     * Calls the specified function *block* with *this* value as its receiver and returns *this* value.
     *
     * T.apply(): T {
     *     block(T.): Unit { this/T. ->
     *         ...
     *     }
     *     return T
     * }
     *
     * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/apply.html].
     */
    fun apply() {
        val argument: String? = "String?"

        val result1: String? = argument.apply {
            classMember()

            this                        // argument (String?)

            //it

            val a: Int? = this?.length
            //val b: Int = length       not allowed on nullable receiver String?

            // no return (Unit)
        }
        val result2: String? = argument?.apply {
            classMember()

            this                        // argument (String)

            //it

            val a: Int = this.length
            val b: Int = length

            // no return (Unit)
        }
    }

    /**
     * fun <T, R> T.let(block: (T) -> R): R
     * Calls the specified function *block* with *this* value as its argument and returns its result.
     *
     * T.let(): R {
     *     return (
     *         block(T): R { it: T ->
     *             ...
     *             return R
     *         }
     *     )
     * }
     *
     * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/let.html].
     */
    fun let() {
        val argument: String? = "String?"

        val result1: Int = argument.let {
            this                        // StdlibCheatSheet
            this.classMember()
            classMember()

            it                          // argument? (String?)
            val a: Int? = it?.length
            //val b: Int? = length

            123 // return anything (R)
        }
        val result2: Int? = argument?.let {
            this                        // StdlibCheatSheet
            this.classMember()
            classMember()

            it                          // argument (String)
            val a: Int = it.length
            //val b: Int = length

            123 // return anything (R)
        }
    }

    /**
     * fun <T, R> T.run(block: T.() -> R): R
     * Calls the specified function *block* with *this* value as its receiver and returns its result.
     *
     * T.run(): R {
     *     return (
     *         block(T.): R { this/T. ->
     *             ...
     *             return R
     *         }
     *     )
     * }
     *
     * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run.html].
     */
    fun run() {
        val argument: String? = "String?"

        val result1: Int = argument.run {
            classMember()

            this                        // argument (String?)

            //it

            val a: Int? = this?.length
            //val b: Int = length       not allowed on nullable receiver String?

            123 // return anything (R)
        }
        val result2: Int? = argument?.run {
            classMember()

            this                        // argument (String)

            //it

            val a: Int = this.length
            val b: Int = length

            123 // return anything (R)
        }
    }

    /**
     * fun <T, R> with(receiver: T, block: T.() -> R): R
     * Calls the specified function *block* with the given *receiver* as its receiver and returns its result.
     *
     * with(T): R {
     *     return (
     *         block(T.): R { this/T. ->
     *             ...
     *             return R
     *         }
     *     )
     * }
     *
     * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/with.html].
     */
    fun with() {
        val argument: String? = "String?"

        val result1: Int = with(argument) {
            classMember()

            this                        // argument (String?)

            //it

            val a: Int? = this?.length
            //val b: Int = length       not allowed on nullable receiver String?

            123 // return anything (R)
        }
        // Not that Safe Calls (https://kotlinlang.org/docs/reference/null-safety.html#safe-calls) are not possible in this case.
        val result2: Int? = with(argument!!) {
            classMember()

            this                        // argument (String)

            //it

            val a: Int = this.length
            val b: Int = length

            123 // return anything (R)
        }
    }

    /**
     * fun <R> run(block: () -> R): R
     * Calls the specified function *block* and returns its result.
     *
     * run(): R {
     *     return (
     *         block(): R {
     *             ...
     *             return R
     *         }
     *     )
     * }
     *
     * See [https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run.html].
     */
    fun runBlock() {
        val result1: Int = run {
            this                        // StdlibCheatSheet
            this.classMember()
            classMember()

            //it

            123 // return anything (R)
        }
    }

}