Added Kotlin Contracts (#41)

* Added contracts for ifExtensions

* Updated version

* Improved test case

Co-authored-by: tvkanters <tvkanters@gmail.com>

README.md

@@ -659,6 +659,11 @@ Contributors: Timon Kanters, Jeroen Erik Jensen, Krzysztof Karczewski
 
 ## Release notes
 
+### 1.6.3
+
+* Added [Kotlin Contracts](https://github.com/Kotlin/KEEP/blob/master/proposals/kotlin-contracts.md) to `ifTrue` and
+ `ifNull`.
+
 ### 1.6.2
 
 * Removed cast extensions.

extensions/pom.xml

@@ -24,7 +24,7 @@
     <parent>
         <groupId>com.tomtom.kotlin</groupId>
         <artifactId>kotlin-tools</artifactId>
-        <version>1.6.2</version>
+        <version>1.6.3</version>
     </parent>
 
     <artifactId>extensions</artifactId>

extensions/src/main/java/com/tomtom/kotlin/extensions/IfExtensions.kt

@@ -16,6 +16,10 @@
 
 package com.tomtom.kotlin.extensions
 
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
+
 /**
  * Executes [block] if `this` is `true`, and returns the result. If `this` is `false` or `null`, it
  * returns `null`.
@@ -32,11 +36,17 @@ package com.tomtom.kotlin.extensions
  * someCondition.ifTrue { someValue }
  * ```
  *
- * It may be inefficient to invert the logic to `someValue.takeIf { someCondition }` when
- * `someValue` isn't readily available.
+ * This is useful when it is not efficient to invert the logic to
+ * `someValue.takeIf { someCondition }` when `someValue` isn't readily available.
  */
-public inline fun <T> Boolean?.ifTrue(block: () -> T): T? =
-    if (this == true) block() else null
+@OptIn(ExperimentalContracts::class)
+public inline fun <T> Boolean?.ifTrue(block: () -> T): T? {
+    contract {
+        callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+        returnsNotNull() implies (this@ifTrue != null)
+    }
+    return if (this == true) block() else null
+}
 
 /**
  * Returns `this` if it is not null. Otherwise, it executes [block] and returns the result.
@@ -72,5 +82,10 @@ public inline fun <T> Boolean?.ifTrue(block: () -> T): T? =
  * chain-calling constructs however, the Elvis operator can easily lead to reduced readability.
  * `let` helps with this, but adds boilerplate that distracts from the functional flow.
  */
-public inline fun <T> T?.ifNull(block: () -> T) : T =
-    this ?: block()
+@OptIn(ExperimentalContracts::class)
+public inline fun <T> T?.ifNull(block: () -> T): T {
+    contract {
+        callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+    }
+    return this ?: block()
+}

extensions/src/test/java/com/tomtom/kotlin/extensions/IfExtensionsTest.kt

@@ -66,6 +66,26 @@ internal class IfExtensionsTest {
         verify(exactly = 0) { ifTrueBlock.invoke() }
     }
 
+    @Test
+    fun `ifTrue contract returnsNotNull`() {
+        // GIVEN
+        val sut: Boolean? = null
+
+        @Suppress("unused")
+        fun Any.callOnNonNull() {}
+
+        // WHEN ifTrue returns something other than null
+        if (sut.ifTrue { 1 } != null) {
+
+            // THEN no null-check is needed on sut
+            sut.callOnNonNull()
+        } else {
+
+            // AND in else it requires a null-check with ?
+             sut?.callOnNonNull()
+        }
+    }
+
     @Test
     fun `ifNull on null`() {
         // GIVEN

memoization/pom.xml

@@ -24,7 +24,7 @@
     <parent>
         <groupId>com.tomtom.kotlin</groupId>
         <artifactId>kotlin-tools</artifactId>
-        <version>1.6.2</version>
+        <version>1.6.3</version>
     </parent>
 
     <artifactId>memoization</artifactId>

pom.xml

@@ -22,7 +22,7 @@
 
     <groupId>com.tomtom.kotlin</groupId>
     <artifactId>kotlin-tools</artifactId>
-    <version>1.6.2</version>
+    <version>1.6.3</version>
     <packaging>pom</packaging>
 
     <name>Kotlin Tools</name>
@@ -231,6 +231,7 @@
                 <configuration>
                     <args>
                         <arg>-Xexplicit-api=strict</arg>
+                        <arg>-Xopt-in=kotlin.RequiresOptIn</arg>
                     </args>
                 </configuration>
             </plugin>

traceevents/pom.xml

@@ -24,7 +24,7 @@
     <parent>
         <groupId>com.tomtom.kotlin</groupId>
         <artifactId>kotlin-tools</artifactId>
-        <version>1.6.2</version>
+        <version>1.6.3</version>
     </parent>
 
     <artifactId>traceevents</artifactId>

uid/pom.xml

@@ -24,7 +24,7 @@
     <parent>
         <groupId>com.tomtom.kotlin</groupId>
         <artifactId>kotlin-tools</artifactId>
-        <version>1.6.2</version>
+        <version>1.6.3</version>
     </parent>
 
     <artifactId>uid</artifactId>