Merge pull request #279 from robstoll/feature/runIf

add also/apply/run to complement the series and a prefix takeUnless

Author: robstoll

README.md

@@ -13,10 +13,13 @@
 -->
 
 # KBox
+
 KBox is a very small but useful utility library for Kotlin (JVM, Android and JS) providing functions which are missing
 in the stdlib such as:
+
 - [failIf](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/failIf.kt)
-- [takeIf](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/takeIf.kt)
+- [prefix takeIf/takeUnless](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/takeIf.kt)
+- [letIf/runIf/alsoIf/applyIf](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/xyzIf.kt)
 - [blankToNull](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/blankToNull.kt)
 - [isNotNullAndNotEmpty/Blank](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/isNotNullAndNot.kt)
 - [identity](https://github.com/robstoll/kbox/tree/main/src/commonMain/kotlin/ch/tutteli/kbox/identity.kt)
@@ -42,6 +45,6 @@ dependencies {
 
 Visit [https://robstoll.github.io/kbox/kdoc](https://robstoll.github.io/kbox/kdoc/).
 
-
 # License
+
 KBox is licensed under [Apache 2.0](http://opensource.org/licenses/Apache2.0).

src/commonMain/kotlin/ch/tutteli/kbox/takeIf.kt

@@ -18,6 +18,7 @@ import kotlin.contracts.contract
 inline fun <R> takeIf(predicate: Boolean, provider: () -> R): R? {
     contract {
         callsInPlace(provider, InvocationKind.AT_MOST_ONCE)
+        //TODO add `predicate holds in block` once we use Kotlin 2.2.20
     }
     return if (predicate) provider() else null
 }

src/commonMain/kotlin/ch/tutteli/kbox/xIf.kt

@@ -0,0 +1,91 @@
+package ch.tutteli.kbox
+
+import kotlin.contracts.ExperimentalContracts
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
+
+/**
+ * Delegates to [let] in case the given [predicate] holds, returns `this` otherwise.
+ *
+ * This function shall complement [let] for cases such as invoking a builder method conditionally which without [letIf]
+ * would be written as follows `if (predicate) t.let { ... } else t`
+ *
+ * @since 3.2.0
+ */
+@OptIn(ExperimentalContracts::class)
+inline fun <T : U, R : U, U> T.letIf(predicate: Boolean, block: (T) -> R): U {
+    contract {
+        callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+        //TODO add `predicate holds in block` once we use Kotlin 2.2.20
+    }
+    return if (predicate) let(block) else this
+}
+
+/**
+ * Delegates to [run] in case the given [predicate] holds, returns `this` otherwise.
+ *
+ * This function shall complement [run] for cases such as invoking a builder method conditionally which without [runIf]
+ * would be written as follows `if (predicate) t.run { ... } else t`
+ *
+ * @since 3.2.0
+ */
+@OptIn(ExperimentalContracts::class)
+inline fun <T : U, R : U, U> T.runIf(predicate: Boolean, block: T.() -> R): U {
+    contract {
+        callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+        //TODO add `predicate holds in block` once we use Kotlin 2.2.20
+    }
+    return if (predicate) run(block) else this
+}
+
+/**
+ * Delegates to [also] in case the given [predicate] holds, returns `this` otherwise.
+ *
+ * This function shall complement [also] and make simple conditional based side effects more readable.
+ *
+ * @since 3.2.0
+ */
+@OptIn(ExperimentalContracts::class)
+inline fun <T> T.alsoIf(predicate: Boolean, block: (T) -> Unit): T {
+    contract {
+        callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+        //TODO add `predicate holds in block` once we use Kotlin 2.2.20
+    }
+    return if (predicate) also(block) else this
+}
+
+/**
+ * Delegates to [apply] in case the given [predicate] holds, returns `this` otherwise.
+ *
+ * This function shall complement [apply] and make simple conditional based side effects more readable.
+ *
+ * @since 3.2.0
+ */
+@OptIn(ExperimentalContracts::class)
+inline fun <T> T.applyIf(predicate: Boolean, block: T.() -> Unit): T {
+    contract {
+        callsInPlace(block, InvocationKind.AT_MOST_ONCE)
+        //TODO add `predicate holds in block` once we use Kotlin 2.2.20
+    }
+    return if (predicate) apply(block) else this
+}
+
+/**
+ * Returns `null` if the [predicate] holds, calls the [provider] otherwise.
+ *
+ * This function shall complement [kotlin.takeUnless] for cases where the cost to call the provider
+ * is high or the code involved to define the provider is long and a postfix `takeUnless` is less readable
+ * than stating it at the beginning.
+ *
+ * @since 3.2.0
+ */
+//TODO move to xIf with 4.0.0
+@OptIn(ExperimentalContracts::class)
+inline fun <R> takeUnless(predicate: Boolean, provider: () -> R): R? {
+    contract {
+        callsInPlace(provider, InvocationKind.AT_MOST_ONCE)
+        //TODO add `predicate holds in block` once we use Kotlin 2.2.20
+    }
+    return if (predicate.not()) provider() else null
+}
+