Deprecate on{Success,Failure} terminology in favour of on{Ok,Err}

The new indexed variants prove that the naming becomes too verbose, so
going with Ok/Err in the function names proves more readable:

- onSuccess → onOk
- onFailure → onErr
- onEachSuccess → onEachOk
- onEachSuccessIndexed → onEachOkIndexed
- onEachFailure → onEachErr
- onEachFailureIndexed → onEachErrIndexed

Author: michaelbull

kotlin-result-coroutines/src/commonMain/kotlin/com/github/michaelbull/result/coroutines/RunSuspendCatching.kt

@@ -8,11 +8,10 @@ import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
 /**
- * Calls the specified function [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. If the encapsulated failure is a
- * [CancellationException], the exception is thrown to indicate  _normal_ cancellation of a
- * coroutine.
+ * Calls the specified function [block] and returns its encapsulated result if invocation was ok,
+ * catching any [Throwable] exception that was thrown from the [block] function execution and
+ * encapsulating it as an error. If the encapsulated error is a [CancellationException], the
+ * exception is thrown to indicate _normal_ cancellation of a coroutine.
  */
 public inline fun <V> runSuspendCatching(block: () -> V): Result<V, Throwable> {
     contract {
@@ -26,10 +25,10 @@ public inline fun <V> runSuspendCatching(block: () -> V): Result<V, Throwable> {
 
 /**
  * Calls the specified function [block] with [this] value as its receiver 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. If the
- * encapsulated failure is a [CancellationException], the exception is thrown to indicate  _normal_
- * cancellation of a coroutine.
+ * encapsulated result if invocation was ok, catching any [Throwable] exception that was thrown
+ * from the [block] function execution and encapsulating it as an error. If the encapsulated error
+ * is a [CancellationException], the exception is thrown to indicate _normal_ cancellation of a
+ * coroutine.
  */
 public inline infix fun <T, V> T.runSuspendCatching(block: T.() -> V): Result<V, Throwable> {
     contract {

kotlin-result-coroutines/src/commonTest/kotlin/com/github/michaelbull/result/coroutines/RunSuspendCatchingTest.kt

@@ -2,7 +2,7 @@ package com.github.michaelbull.result.coroutines
 
 import com.github.michaelbull.result.Err
 import com.github.michaelbull.result.Ok
-import com.github.michaelbull.result.onSuccess
+import com.github.michaelbull.result.onOk
 import kotlinx.coroutines.CoroutineName
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.delay
@@ -27,7 +27,7 @@ class RunSuspendCatchingTest {
                 }
 
                 // The coroutine should be cancelled before reaching here
-                result.onSuccess { value = it }
+                result.onOk { value = it }
             }
 
             testScheduler.advanceTimeBy(2_000)

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Deprecations.kt

@@ -1,5 +1,8 @@
 package com.github.michaelbull.result
 
+import kotlin.contracts.InvocationKind
+import kotlin.contracts.contract
+
 @Deprecated("Use filterOk instead.", ReplaceWith("filterOk()"))
 public fun <V, E> Iterable<Result<V, E>>.filterValues(): List<V> {
     return filterOk()
@@ -19,3 +22,21 @@ public fun <V, E, C : MutableCollection<in V>> Iterable<Result<V, E>>.filterValu
 public fun <V, E, C : MutableCollection<in E>> Iterable<Result<V, E>>.filterErrorsTo(destination: C): C {
     return filterErrTo(destination)
 }
+
+@Deprecated("Use onOk instead.", ReplaceWith("onOk(action)"))
+public inline infix fun <V, E> Result<V, E>.onSuccess(action: (V) -> Unit): Result<V, E> {
+    contract {
+        callsInPlace(action, InvocationKind.AT_MOST_ONCE)
+    }
+
+    return onOk(action)
+}
+
+@Deprecated("Use onErr instead.", ReplaceWith("onErr(action)"))
+public inline infix fun <V, E> Result<V, E>.onFailure(action: (E) -> Unit): Result<V, E> {
+    contract {
+        callsInPlace(action, InvocationKind.AT_MOST_ONCE)
+    }
+
+    return onErr(action)
+}

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Factory.kt

@@ -4,9 +4,9 @@ import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
 /**
- * Calls the specified function [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.
+ * Calls the specified function [block] and returns its encapsulated result if invocation was ok,
+ * catching any [Throwable] exception that was thrown from the [block] function execution and
+ * encapsulating it as an error.
  */
 public inline fun <V> runCatching(block: () -> V): Result<V, Throwable> {
     contract {
@@ -22,8 +22,8 @@ public inline fun <V> runCatching(block: () -> V): Result<V, Throwable> {
 
 /**
  * Calls the specified function [block] with [this] value as its receiver 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.
+ * encapsulated result if invocation was ok, catching any [Throwable] exception that was thrown
+ * from the [block] function execution and encapsulating it as an error.
  */
 public inline infix fun <T, V> T.runCatching(block: T.() -> V): Result<V, Throwable> {
     contract {

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Iterable.kt

@@ -307,17 +307,17 @@ public inline fun <V, E, U : Any, C : MutableCollection<in U>> Iterable<V>.mapRe
  * Performs the given [action] on each [ok][Result.isOk] value and returns the collection itself
  * afterwards.
  */
-public inline fun <V, E> Iterable<Result<V, E>>.onEachSuccess(action: (V) -> Unit): Iterable<Result<V, E>> {
+public inline fun <V, E> Iterable<Result<V, E>>.onEachOk(action: (V) -> Unit): Iterable<Result<V, E>> {
     return onEach { result ->
-        result.onSuccess(action)
+        result.onOk(action)
     }
 }
 
 /**
  * Performs the given [action] on each [ok][Result.isOk] value and its index and returns the
  * collection itself afterwards.
  */
-public inline fun <V, E> Iterable<Result<V, E>>.onEachSuccessIndexed(action: (index: Int, V) -> Unit): Iterable<Result<V, E>> {
+public inline fun <V, E> Iterable<Result<V, E>>.onEachOkIndexed(action: (index: Int, V) -> Unit): Iterable<Result<V, E>> {
     return onEachIndexed { index, result ->
         if (result.isOk) {
             action(index, result.value)
@@ -329,17 +329,17 @@ public inline fun <V, E> Iterable<Result<V, E>>.onEachSuccessIndexed(action: (in
  * Performs the given [action] on each [error][Result.isErr] value and returns the collection itself
  * afterwards.
  */
-public inline fun <V, E> Iterable<Result<V, E>>.onEachFailure(action: (E) -> Unit): Iterable<Result<V, E>> {
+public inline fun <V, E> Iterable<Result<V, E>>.onEachErr(action: (E) -> Unit): Iterable<Result<V, E>> {
     return onEach { result ->
-        result.onFailure(action)
+        result.onErr(action)
     }
 }
 
 /**
  * Performs the given [action] on each [error][Result.isErr] value and its index and returns the
  * collection itself afterwards.
  */
-public inline fun <V, E> Iterable<Result<V, E>>.onEachFailureIndexed(action: (index: Int, E) -> Unit): Iterable<Result<V, E>> {
+public inline fun <V, E> Iterable<Result<V, E>>.onEachErrIndexed(action: (index: Int, E) -> Unit): Iterable<Result<V, E>> {
     return onEachIndexed { index, result ->
         if (result.isErr) {
             action(index, result.error)

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/On.kt

@@ -8,7 +8,7 @@ import kotlin.contracts.contract
  *
  * - Rust: [Result.inspect](https://doc.rust-lang.org/std/result/enum.Result.html#method.inspect)
  */
-public inline infix fun <V, E> Result<V, E>.onSuccess(action: (V) -> Unit): Result<V, E> {
+public inline infix fun <V, E> Result<V, E>.onOk(action: (V) -> Unit): Result<V, E> {
     contract {
         callsInPlace(action, InvocationKind.AT_MOST_ONCE)
     }
@@ -25,7 +25,7 @@ public inline infix fun <V, E> Result<V, E>.onSuccess(action: (V) -> Unit): Resu
  *
  * - Rust [Result.inspect_err](https://doc.rust-lang.org/std/result/enum.Result.html#method.inspect_err)
  */
-public inline infix fun <V, E> Result<V, E>.onFailure(action: (E) -> Unit): Result<V, E> {
+public inline infix fun <V, E> Result<V, E>.onErr(action: (E) -> Unit): Result<V, E> {
     contract {
         callsInPlace(action, InvocationKind.AT_MOST_ONCE)
     }

kotlin-result/src/commonTest/kotlin/com/github/michaelbull/result/IterableTest.kt

@@ -338,7 +338,7 @@ class IterableTest {
         }
     }
 
-    class OnEachSuccess {
+    class OnEachOk {
 
         @Test
         fun invokesActionForOkResults() {
@@ -348,7 +348,7 @@ class IterableTest {
                 Ok(1),
                 Err("error"),
                 Ok(2),
-            ).onEachSuccess(collected::add)
+            ).onEachOk(collected::add)
 
             assertEquals(
                 expected = listOf(1, 2),
@@ -364,7 +364,7 @@ class IterableTest {
                 Ok(2),
             )
 
-            val result = items.onEachSuccess { }
+            val result = items.onEachOk { }
 
             assertEquals(
                 expected = items,
@@ -373,7 +373,7 @@ class IterableTest {
         }
     }
 
-    class OnEachSuccessIndexed {
+    class OnEachOkIndexed {
 
         @Test
         fun invokesActionWithIndexForOkResults() {
@@ -385,7 +385,7 @@ class IterableTest {
                 Ok(20),
                 Err("error"),
                 Ok(30),
-            ).onEachSuccessIndexed { index, value -> collected.add(index to value) }
+            ).onEachOkIndexed { index, value -> collected.add(index to value) }
 
             assertEquals(
                 expected = listOf(0 to 10, 2 to 20, 4 to 30),
@@ -394,7 +394,7 @@ class IterableTest {
         }
     }
 
-    class OnEachFailure {
+    class OnEachErr {
 
         @Test
         fun invokesActionForErrResults() {
@@ -405,7 +405,7 @@ class IterableTest {
                 Err("error1"),
                 Ok(2),
                 Err("error2"),
-            ).onEachFailure(collected::add)
+            ).onEachErr(collected::add)
 
             assertEquals(
                 expected = listOf("error1", "error2"),
@@ -421,7 +421,7 @@ class IterableTest {
                 Ok(2),
             )
 
-            val result = items.onEachFailure { }
+            val result = items.onEachErr { }
 
             assertEquals(
                 expected = items,
@@ -430,7 +430,7 @@ class IterableTest {
         }
     }
 
-    class OnEachFailureIndexed {
+    class OnEachErrIndexed {
 
         @Test
         fun invokesActionWithIndexForErrResults() {
@@ -442,7 +442,7 @@ class IterableTest {
                 Ok(2),
                 Err("error2"),
                 Ok(3),
-            ).onEachFailureIndexed { index, error -> collected.add(index to error) }
+            ).onEachErrIndexed { index, error -> collected.add(index to error) }
 
             assertEquals(
                 expected = listOf(1 to "error1", 3 to "error2"),

kotlin-result/src/commonTest/kotlin/com/github/michaelbull/result/OnTest.kt

@@ -7,13 +7,13 @@ class OnTest {
     object CounterError
     class Counter(var count: Int)
 
-    class OnSuccess {
+    class OnOk {
 
         @Test
         fun invokesActionIfOk() {
             val counter = Counter(50)
 
-            Ok(counter).onSuccess { it.count += 50 }
+            Ok(counter).onOk { it.count += 50 }
 
             assertEquals(
                 expected = 100,
@@ -25,7 +25,7 @@ class OnTest {
         fun invokesNothingIfErr() {
             val counter = Counter(200)
 
-            Err(CounterError).onSuccess { counter.count -= 50 }
+            Err(CounterError).onOk { counter.count -= 50 }
 
             assertEquals(
                 expected = 200,
@@ -34,13 +34,13 @@ class OnTest {
         }
     }
 
-    class OnFailure {
+    class OnErr {
 
         @Test
         fun invokesActionIfErr() {
             val counter = Counter(555)
 
-            Err(CounterError).onFailure { counter.count += 100 }
+            Err(CounterError).onErr { counter.count += 100 }
 
             assertEquals(
                 expected = 655,
@@ -52,7 +52,7 @@ class OnTest {
         fun invokesNothingIfOk() {
             val counter = Counter(1020)
 
-            Ok("hello").onFailure { counter.count = 1030 }
+            Ok("hello").onErr { counter.count = 1030 }
 
             assertEquals(
                 expected = 1020,