Add nullable fns to replace option fns (#191)

Co-authored-by: Tavish Pegram <[email protected]>

Author: Tavish Pegram

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/core/Either.kt

@@ -799,9 +799,30 @@ sealed class Either<out A, out B> : EitherOf<A, B> {
    * Left(12).toOption()  // Result: None
    * ```
    */
+  @Deprecated("Deprecated, use `orNull` instead", ReplaceWith("orNull()"))
   fun toOption(): Option<B> =
     fold({ None }, { Some(it) })
 
+  /**
+   * Returns the right value if it exists, otherwise null
+   *
+   * Example:
+   * ```kotlin:ank:playground
+   * import arrow.core.Right
+   * import arrow.core.Left
+   *
+   * //sampleStart
+   * val right = Right(12).orNull() // Result: 12
+   * val left = Left(12).orNull()   // Result: null
+   * //sampleEnd
+   * fun main() {
+   *   println("right = $right")
+   *   println("left = $left")
+   * }
+   * ```
+   */
+  fun orNull(): B? = fold({ null }, { it })
+
   /**
    * The left side of the disjoint union, as opposed to the [Right] side.
    */

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/core/Ior.kt

@@ -76,7 +76,7 @@ sealed class Ior<out A, out B> : IorOf<A, B> {
      * @return [None] if both [oa] and [ob] are [None]. Otherwise [Some] wrapping
      * an [Ior.Left], [Ior.Right], or [Ior.Both] if [oa], [ob], or both are defined (respectively).
      */
-
+    @Deprecated("Deprecated, use `fromNullables` instead", ReplaceWith("fromNullables(a, b)"))
     fun <A, B> fromOptions(oa: Option<A>, ob: Option<B>): Option<Ior<A, B>> = when (oa) {
       is Some -> when (ob) {
         is Some -> Some(Both(oa.t, ob.t))
@@ -88,6 +88,27 @@ sealed class Ior<out A, out B> : IorOf<A, B> {
       }
     }
 
+    /**
+     * Create an [Ior] from two nullables if at least one of them is defined.
+     *
+     * @param a an element (nullable) for the left side of the [Ior]
+     * @param b an element (nullable) for the right side of the [Ior]
+     *
+     * @return [null] if both [a] and [b] are [null]. Otherwise
+     * an [Ior.Left], [Ior.Right], or [Ior.Both] if [a], [b], or both are defined (respectively).
+     */
+    fun <A, B> fromNullables(a: A?, b: B?): Ior<A, B>? =
+      when (a != null) {
+        true -> when (b != null) {
+          true -> Both(a, b)
+          false -> Left(a)
+        }
+        false -> when (b != null) {
+          true -> Right(b)
+          false -> null
+        }
+    }
+
     private tailrec fun <L, A, B> Semigroup<L>.loop(v: Ior<L, Either<A, B>>, f: (A) -> IorOf<L, Either<A, B>>): Ior<L, B> = when (v) {
       is Left -> Left(v.value)
       is Right -> when (v.value) {
@@ -235,17 +256,44 @@ sealed class Ior<out A, out B> : IorOf<A, B> {
    *
    * Example:
    * ```
-   * Right(12).pad() // Result: Pair(None, Some(12))
-   * Left(12).pad()  // Result: Pair(Some(12), None)
-   * Both("power", 12).pad()  // Result: Pair(Some("power"), Some(12))
+   * Ior.Right(12).pad()          // Result: Pair(None, Some(12))
+   * Ior.Left(12).pad()           // Result: Pair(Some(12), None)
+   * Ior.Both("power", 12).pad()  // Result: Pair(Some("power"), Some(12))
    * ```
    */
+  @Deprecated("Deprecated, use `padNull` instead", ReplaceWith("padNull()"))
   fun pad(): Pair<Option<A>, Option<B>> = fold(
     { Pair(Some(it), None) },
     { Pair(None, Some(it)) },
     { a, b -> Pair(Some(a), Some(b)) }
   )
 
+  /**
+   * Return this [Ior] as [Pair] of nullables]
+   *
+   * Example:
+   * ```kotlin:ank:playground
+   * import arrow.core.Ior
+   *
+   * //sampleStart
+   * val right = Ior.Right(12).padNull()         // Result: Pair(null, 12)
+   * val left = Ior.Left(12).padNull()           // Result: Pair(12, null)
+   * val both = Ior.Both("power", 12).padNull()  // Result: Pair("power", 12)
+   * //sampleEnd
+   *
+   * fun main() {
+   *   println("right = $right")
+   *   println("left = $left")
+   *   println("both = $both")
+   * }
+   * ```
+   */
+  fun padNull(): Pair<A?, B?> = fold(
+    { Pair(it, null) },
+    { Pair(null, it) },
+    { a, b -> Pair(a, b) }
+  )
+
   /**
    * Returns a [Either.Right] containing the [Right] value or `B` if this is [Right] or [Both]
    * and [Either.Left] if this is a [Left].
@@ -271,9 +319,33 @@ sealed class Ior<out A, out B> : IorOf<A, B> {
    * Both(12, "power").toOption()  // Result: Some("power")
    * ```
    */
+  @Deprecated("Deprecated, use `orNull` instead", ReplaceWith("orNull()"))
   fun toOption(): Option<B> =
     fold({ None }, { Some(it) }, { _, b -> Some(b) })
 
+  /**
+   * Returns the [Right] value or `B` if this is [Right] or [Both]
+   * and [null] if this is a [Left].
+   *
+   * Example:
+   * ```kotlin:ank:playground
+   * import arrow.core.Ior
+   *
+   * //sampleStart
+   * val right = Ior.Right(12).orNull()         // Result: 12
+   * val left = Ior.Left(12).orNull()           // Result: null
+   * val both = Ior.Both(12, "power").orNull()  // Result: "power"
+   * //sampleEnd
+   * fun main() {
+   *   println("right = $right")
+   *   println("left = $left")
+   *   println("both = $both")
+   * }
+   * ```
+   */
+  fun orNull(): B? =
+    fold({ null }, { it }, { _, b -> b })
+
   /**
    * Returns a [Some] containing the [Left] value or `A` if this is [Left] or [Both]
    * and [None] if this is a [Right].
@@ -285,9 +357,34 @@ sealed class Ior<out A, out B> : IorOf<A, B> {
    * Both(12, "power").toLeftOption()  // Result: Some(12)
    * ```
    */
+  @Deprecated("Deprecated, use `leftOrNull` instead", ReplaceWith("leftOrNull()"))
   fun toLeftOption(): Option<A> =
     fold({ Option.just(it) }, { Option.empty() }, { a, _ -> Option.just(a) })
 
+  /**
+   * Returns the [Left] value or `A` if this is [Left] or [Both]
+   * and [null] if this is a [Right].
+   *
+   * Example:
+   * ```kotlin:ank:playground
+   * import arrow.core.Ior
+   *
+   * //sampleStart
+   * val right = Ior.Right(12).leftOrNull()         // Result: null
+   * val left = Ior.Left(12).leftOrNull()           // Result: 12
+   * val both = Ior.Both(12, "power").leftOrNull()  // Result: 12
+   * //sampleEnd
+   *
+   * fun main() {
+   *   println("right = $right")
+   *   println("left = $left")
+   *   println("both = $both")
+   * }
+   * ```
+   */
+  fun leftOrNull(): A? =
+    fold({ it }, { null }, { a, _ -> a })
+
   /**
    * Returns a [Validated.Valid] containing the [Right] value or `B` if this is [Right] or [Both]
    * and [Validated.Invalid] if this is a [Left].

arrow-libs/core/arrow-core-data/src/test/kotlin/arrow/core/EitherTest.kt

@@ -187,6 +187,13 @@ class EitherTest : UnitSpec() {
       }
     }
 
+    "orNull should convert" {
+      forAll { a: Int ->
+        Right(a).orNull() == a &&
+          Left(a).orNull() == null
+      }
+    }
+
     "contains should check value" {
       forAll(Gen.intSmall(), Gen.intSmall()) { a: Int, b: Int ->
         Right(a).contains(a) &&

arrow-libs/core/arrow-core-data/src/test/kotlin/arrow/core/IorTest.kt

@@ -112,6 +112,14 @@ class IorTest : UnitSpec() {
       }
     }
 
+    "padNull() should return the correct Pair of nullables" {
+      forAll { a: Int, b: String ->
+        Ior.Left(a).padNull() == Pair(a, null) &&
+          Ior.Right(b).padNull() == Pair(null, b) &&
+          Ior.Both(a, b).padNull() == Pair(a, b)
+      }
+    }
+
     "toEither() should convert values into a valid Either" {
       forAll { a: Int, b: String ->
         Ior.Left(a).toEither() == Either.Left(a) &&
@@ -128,6 +136,22 @@ class IorTest : UnitSpec() {
       }
     }
 
+    "orNull() should convert right values into a nullable" {
+      forAll { a: Int, b: String ->
+        Ior.Left(a).orNull() == null &&
+          Ior.Right(b).orNull() == b &&
+          Ior.Both(a, b).orNull() == b
+      }
+    }
+
+    "leftOrNull() should convert left values into a nullable" {
+      forAll { a: Int, b: String ->
+        Ior.Left(a).leftOrNull() == a &&
+          Ior.Right(b).leftOrNull() == null &&
+          Ior.Both(a, b).leftOrNull() == a
+      }
+    }
+
     "toValidated() should convert values into a valid Validated" {
       forAll { a: Int, b: String ->
         Ior.Left(a).toValidated() == Invalid(a) &&
@@ -145,6 +169,15 @@ class IorTest : UnitSpec() {
       }
     }
 
+    "fromNullables() should build a correct Ior" {
+      forAll { a: Int, b: String ->
+        Ior.fromNullables(a, null) == Ior.Left(a) &&
+          Ior.fromNullables(a, b) == Ior.Both(a, b) &&
+          Ior.fromNullables(null, b) == Ior.Right(b) &&
+          Ior.fromNullables(null, null) == null
+      }
+    }
+
     "getOrElse() should return value" {
       forAll { a: Int, b: Int ->
         Ior.Right(a).getOrElse { b } == a &&