Merge pull request #14 from grandcentrix/feature/catch_either

Feature: CatchEither

README.md

@@ -67,6 +67,7 @@ successOrNull // property returning the success value if Success or null if Fail
 failureOrNull // property returning the failure value if Failure or null if Success
 onSuccess {} // executes given code block as side effect if Success and returns passed Either value unchanged
 onFailure {} // executes given code block as side effect if Failure and returns passed Either value unchanged
+Either.catch {} // executes the given code and returns its encapsulated result if invocation was successful and catching any exception that was thrown as a failure
 ```
 
 ## Additional Utilities

build.gradle.kts

@@ -10,7 +10,7 @@ buildscript {
 
     allprojects {
         group = "net.grandcentrix.either"
-        version = "1.5"
+        version = "1.6"
     }
 }
 

either/src/main/kotlin/net/grandcentrix/either/Either.kt

@@ -68,6 +68,19 @@ sealed class Either<out F, out S> {
     inline fun onFailure(block: (failure: F) -> Unit): Either<F, S> = also {
         if (it is Failure<F>) block(it.failure)
     }
+
+    companion object {
+
+        /**
+         * Executes the given code [block] and returns its encapsulated result if invocation was successful,
+         * catching any [Throwable] exception that was thrown from the [block] function execution and encapsulating it as a failure.
+         */
+        inline fun <S> catch(block: () -> S): Either<Throwable, S> = try {
+            Success(block())
+        } catch (e: Throwable) {
+            Failure(e)
+        }
+    }
 }
 
 data class Failure<out F>(val failure: F) : Either<F, Nothing>()

either/src/test/kotlin/net/grandcentrix/either/EitherTest.kt

@@ -5,7 +5,6 @@ import org.junit.jupiter.api.Assertions.assertNull
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.fail
 
-
 class EitherTest {
 
     @Test
@@ -172,4 +171,17 @@ class EitherTest {
         val failureOrNull = Success("success result").failureOrNull
         assertNull(failureOrNull)
     }
+
+    @Test
+    fun `when catch with no exception return success`() {
+        val result = Either.catch { "success result" }
+        assertThat(result).isEqualTo(Success("success result"))
+    }
+
+    @Test
+    fun `when catch with exception return failure with exception`() {
+        val exception = IllegalStateException()
+        val result = Either.catch { throw exception }
+        assertThat(result).isEqualTo(Failure(exception))
+    }
 }