Kotlin run function
Kotlin has made our life very easy by providing features like extension functions, nullability check and much more. One such kind of really helpful feature is Scope functions. Once you understand what scope functions are, you will not able to resist yourself from using them.
This post was originally posted at https://agrawalsuneet.github.io/blogs/kotlin-run-function/ and reposted on Medium on 5th June 2021.Scope functions are nothing but the functions which define to the scope of the calling object. We can apply operations on that object within that scope and return the object itself from that scope function or we can even return the result of operation or operations from the scope function.
There are a few scope functions
To keep this article short and to the point, we will talk only about run in this article and all the use cases around it.
run has two variants.
One is an extension function to Template class which takes a lambda (higher-order function) as a parameter, apply contract on it and ultimately return the execution of the lambda we passed as a parameter to it.
Second is not an extension function to Template class but a normal extension function that takes a higher-order function as parameters, applies the operations and return the lambda expression or results. The return type can also be void.
/**
* Calls the specified function [block] and returns its result.
*/
@kotlin.internal.InlineOnly
public inline fun <R> run(block: () -> R): R {
contract {
callsInPlace(block, InvocationKind.EXACTLY_ONCE)
}
return block()
}/**
* Calls the specified function [block] with `this` value as its receiver and returns its result.
*/
@kotlin.internal.InlineOnly
public inline fun <T, R> T.run(block: T.() -> R): R {
contract {
callsInPlace(block, InvocationKind.EXACTLY_ONCE)
}
return block()
}
This clarifies a few things
- The return type of the both run functions are nothing but the last expression we returned from our passed lambda parameters.
- Since its an extension function to the Template class as well as generic without any class, it can be called on any object with or without chaining.
Now let’s understand what is the contract.
The contract is nothing but a contract applied to the passed lambda as a parameter.
/**
* Specifies the contract of a function.
*
* The contract description must be at the beginning of a function and have at least one effect.
*
* Only the top-level functions can have a contract for now.
*
* @param builder the lambda where the contract of a function is described with the help of the [ContractBuilder] members.
*
@ContractsDsl
@ExperimentalContracts
@InlineOnly
@SinceKotlin("1.3")
@Suppress("UNUSED_PARAMETER")
public inline fun contract(builder: ContractBuilder.() -> Unit) { }This is exactly the same contract as to any other scope function. This superimposes some conditions on the lambda we passed as a parameter to the run function. What conditions it superimposed, we need to check the parameter of the contract
