Add catch with transform (#3751)

Author: tKe

arrow-libs/core/arrow-core/api/android/arrow-core.api

@@ -1043,6 +1043,7 @@ public final class arrow/core/raise/RaiseKt {
 	public static final fun _foldOrThrow (Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun _merge (Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun catch (Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
+	public static final fun catch (Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun catch (Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function2;)Lkotlin/jvm/functions/Function1;
 	public static final fun catch (Lkotlin/jvm/functions/Function2;)Lkotlin/jvm/functions/Function2;
 	public static final fun catch (Lkotlin/jvm/functions/Function2;Lkotlin/jvm/functions/Function3;)Lkotlin/jvm/functions/Function2;

arrow-libs/core/arrow-core/api/arrow-core.klib.api

@@ -1016,6 +1016,7 @@ final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> (kotlin/Result<#A>).arrow.co
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise.context/either(kotlin/Function1<arrow.core.raise/Raise<#A>, #B>): arrow.core/Either<#A, #B> // arrow.core.raise.context/either|either(kotlin.Function1<arrow.core.raise.Raise<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise.context/ior(noinline kotlin/Function2<#A, #A, #A>, kotlin/Function1<arrow.core.raise/IorRaise<#A>, #B>): arrow.core/Ior<#A, #B> // arrow.core.raise.context/ior|ior(kotlin.Function2<0:0,0:0,0:0>;kotlin.Function1<arrow.core.raise.IorRaise<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise.context/iorNel(noinline kotlin/Function2<arrow.core/NonEmptyList<#A>, arrow.core/NonEmptyList<#A>, arrow.core/NonEmptyList<#A>> = ..., kotlin/Function1<arrow.core.raise/IorRaise<arrow.core/NonEmptyList<#A>>, #B>): arrow.core/Ior<arrow.core/NonEmptyList<#A>, #B> // arrow.core.raise.context/iorNel|iorNel(kotlin.Function2<arrow.core.NonEmptyList<0:0>,arrow.core.NonEmptyList<0:0>,arrow.core.NonEmptyList<0:0>>;kotlin.Function1<arrow.core.raise.IorRaise<arrow.core.NonEmptyList<0:0>>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
+final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise/catch(kotlin/Function0<#A>, kotlin/Function1<#A, #B>, kotlin/Function1<kotlin/Throwable, #B>): #B // arrow.core.raise/catch|catch(kotlin.Function0<0:0>;kotlin.Function1<0:0,0:1>;kotlin.Function1<kotlin.Throwable,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise/eagerEffect(noinline kotlin/Function1<arrow.core.raise/Raise<#A>, #B>): kotlin/Function1<arrow.core.raise/Raise<#A>, #B> // arrow.core.raise/eagerEffect|eagerEffect(kotlin.Function1<arrow.core.raise.Raise<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise/effect(noinline kotlin.coroutines/SuspendFunction1<arrow.core.raise/Raise<#A>, #B>): kotlin.coroutines/SuspendFunction1<arrow.core.raise/Raise<#A>, #B> // arrow.core.raise/effect|effect(kotlin.coroutines.SuspendFunction1<arrow.core.raise.Raise<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
 final inline fun <#A: kotlin/Any?, #B: kotlin/Any?> arrow.core.raise/either(kotlin/Function1<arrow.core.raise/Raise<#A>, #B>): arrow.core/Either<#A, #B> // arrow.core.raise/either|either(kotlin.Function1<arrow.core.raise.Raise<0:0>,0:1>){0§<kotlin.Any?>;1§<kotlin.Any?>}[0]
@@ -1054,6 +1055,7 @@ final inline fun <#A: kotlin/Comparable<#A>> (arrow.core/NonEmptyList<#A>).arrow
 final inline fun <#A: reified kotlin/Any?> (arrow.core/Option<*>).arrow.core/filterIsInstance(): arrow.core/Option<#A> // arrow.core/filterIsInstance|filterIsInstance@arrow.core.Option<*>(){0§<kotlin.Any?>}[0]
 final inline fun <#A: reified kotlin/Throwable, #B: kotlin/Any?, #C: kotlin/Any?> (kotlin.coroutines/SuspendFunction1<arrow.core.raise/Raise<#B>, #C>).arrow.core.raise/catch(crossinline kotlin.coroutines/SuspendFunction2<arrow.core.raise/Raise<#B>, #A, #C>): kotlin.coroutines/SuspendFunction1<arrow.core.raise/Raise<#B>, #C> // arrow.core.raise/catch|catch@kotlin.coroutines.SuspendFunction1<arrow.core.raise.Raise<0:1>,0:2>(kotlin.coroutines.SuspendFunction2<arrow.core.raise.Raise<0:1>,0:0,0:2>){0§<kotlin.Throwable>;1§<kotlin.Any?>;2§<kotlin.Any?>}[0]
 final inline fun <#A: reified kotlin/Throwable, #B: kotlin/Any?, #C: kotlin/Any?> (kotlin/Function1<arrow.core.raise/Raise<#B>, #C>).arrow.core.raise/catch(crossinline kotlin/Function2<arrow.core.raise/Raise<#B>, #A, #C>): kotlin/Function1<arrow.core.raise/Raise<#B>, #C> // arrow.core.raise/catch|catch@kotlin.Function1<arrow.core.raise.Raise<0:1>,0:2>(kotlin.Function2<arrow.core.raise.Raise<0:1>,0:0,0:2>){0§<kotlin.Throwable>;1§<kotlin.Any?>;2§<kotlin.Any?>}[0]
+final inline fun <#A: reified kotlin/Throwable, #B: kotlin/Any?, #C: kotlin/Any?> arrow.core.raise/catch(kotlin/Function0<#B>, kotlin/Function1<#B, #C>, kotlin/Function1<#A, #C>): #C // arrow.core.raise/catch|catch(kotlin.Function0<0:1>;kotlin.Function1<0:1,0:2>;kotlin.Function1<0:0,0:2>){0§<kotlin.Throwable>;1§<kotlin.Any?>;2§<kotlin.Any?>}[0]
 final inline fun <#A: reified kotlin/Throwable, #B: kotlin/Any?, #C: kotlin/Any?> arrow.core.raise/recover(kotlin/Function1<arrow.core.raise/Raise<#B>, #C>, kotlin/Function1<#B, #C>, kotlin/Function1<#A, #C>): #C // arrow.core.raise/recover|recover(kotlin.Function1<arrow.core.raise.Raise<0:1>,0:2>;kotlin.Function1<0:1,0:2>;kotlin.Function1<0:0,0:2>){0§<kotlin.Throwable>;1§<kotlin.Any?>;2§<kotlin.Any?>}[0]
 final inline fun <#A: reified kotlin/Throwable, #B: kotlin/Any?> arrow.core.raise/catch(kotlin/Function0<#B>, kotlin/Function1<#A, #B>): #B // arrow.core.raise/catch|catch(kotlin.Function0<0:1>;kotlin.Function1<0:0,0:1>){0§<kotlin.Throwable>;1§<kotlin.Any?>}[0]
 final inline fun arrow.core.raise.context/impure(kotlin/Function1<arrow.core.raise/SingletonRaise<kotlin/Unit>, kotlin/Unit>) // arrow.core.raise.context/impure|impure(kotlin.Function1<arrow.core.raise.SingletonRaise<kotlin.Unit>,kotlin.Unit>){}[0]

arrow-libs/core/arrow-core/api/jvm/arrow-core.api

@@ -1043,6 +1043,7 @@ public final class arrow/core/raise/RaiseKt {
 	public static final fun _foldOrThrow (Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun _merge (Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun catch (Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
+	public static final fun catch (Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function1;)Ljava/lang/Object;
 	public static final fun catch (Lkotlin/jvm/functions/Function1;Lkotlin/jvm/functions/Function2;)Lkotlin/jvm/functions/Function1;
 	public static final fun catch (Lkotlin/jvm/functions/Function2;)Lkotlin/jvm/functions/Function2;
 	public static final fun catch (Lkotlin/jvm/functions/Function2;Lkotlin/jvm/functions/Function3;)Lkotlin/jvm/functions/Function2;

arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/Either.kt

@@ -832,13 +832,13 @@ public sealed class Either<out A, out B> {
     @JvmStatic
     public inline fun <R> catch(f: () -> R): Either<Throwable, R> {
       contract { callsInPlace(f, InvocationKind.AT_MOST_ONCE) }
-      return arrow.core.raise.catch({ f().right() }) { it.left() }
+      return arrow.core.raise.catch(f, ::Right, ::Left)
     }
 
     @JvmStatic
     public inline fun <reified T : Throwable, R> catchOrThrow(f: () -> R): Either<T, R> {
       contract { callsInPlace(f, InvocationKind.AT_MOST_ONCE) }
-      return arrow.core.raise.catch<T, Either<T, R>>({ f().right() }) { it.left() }
+      return arrow.core.raise.catch<T, _, _>(f, ::Right, ::Left)
     }
 
     public inline fun <E, A, B, Z> zipOrAccumulate(

arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/Raise.kt

@@ -477,6 +477,25 @@ public inline fun <A> catch(block: () -> A, catch: (throwable: Throwable) -> A):
   }
 }
 
+/**
+ * Allows safely catching exceptions without capturing [CancellationException],
+ * or fatal exceptions like `OutOfMemoryError` or `VirtualMachineError` on the JVM.
+ *
+ * Depending on the outcome of the block, one of the two lambdas is run:
+ * - _success_ [transform] result of [A] to a value of [B].
+ * - _thrown_ [catch] the thrown [Throwable] and calculate a value of [B].
+ */
+@RaiseDSL
+public inline fun <A, B> catch(block: () -> A, transform: (value: A) -> B, catch: (throwable: Throwable) -> B): B {
+  contract {
+    callsInPlace(block, AT_MOST_ONCE)
+    callsInPlace(transform, AT_MOST_ONCE)
+    callsInPlace(catch, AT_MOST_ONCE)
+  }
+  val value = catch({ block() }, { return catch(it) })
+  return transform(value)
+}
+
 /**
  * Allows safely catching exceptions of type `T` without capturing [CancellationException],
  * or fatal exceptions like `OutOfMemoryError` or `VirtualMachineError` on the JVM.
@@ -518,6 +537,25 @@ public inline fun <reified T : Throwable, A> catch(block: () -> A, catch: (t: T)
   return catch(block) { t: Throwable -> if (t is T) catch(t) else throw t }
 }
 
+/**
+ * Allows safely catching exceptions of type `T` without capturing [CancellationException],
+ * or fatal exceptions like `OutOfMemoryError` or `VirtualMachineError` on the JVM.
+ *
+ * Depending on the outcome of the block, one of the two lambdas is run:
+ * - _success_ [transform] result of [A] to a value of [B].
+ * - _thrown_ [catch] the thrown [T] and calculate a value of [B].
+ */
+@RaiseDSL
+@JvmName("catchReified")
+public inline fun <reified T : Throwable, A, B> catch(block: () -> A, transform: (A) -> B, catch: (t: T) -> B): B {
+  contract {
+    callsInPlace(block, AT_MOST_ONCE)
+    callsInPlace(transform, AT_MOST_ONCE)
+    callsInPlace(catch, AT_MOST_ONCE)
+  }
+  return catch(block, transform) { t: Throwable -> if (t is T) catch(t) else throw t }
+}
+
 /**
  * Ensures that the [condition] is met;
  * otherwise, [Raise.raise]s a logical failure of type [Error].