Add Either.flatMapNull

mirai-core-utils/src/commonMain/kotlin/Either.kt

@@ -1,10 +1,10 @@
 /*
- * Copyright 2019-2021 Mamoe Technologies and contributors.
+ * Copyright 2019-2022 Mamoe Technologies and contributors.
  *
- *  此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
- *  Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
  *
- *  https://github.com/mamoe/mirai/blob/master/LICENSE
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
  */
 
 @file:Suppress("NOTHING_TO_INLINE", "unused")
@@ -138,6 +138,18 @@ public value class Either<out L : Any, out R : Any?> private constructor(
             onRight = { Result.success(it) }
         )
 
+        /**
+         * Invoke and return [block] if the backing value of this [Either] is null. Returns `this` otherwise.
+         */
+        public inline fun <reified L : SuperL, reified R : SuperR, SuperL : Any, SuperR> Either<L, R?>.flatMapNull(
+            block: () -> Either<SuperL, SuperR?>
+        ): Either<SuperL, SuperR?> {
+            if (this.leftOrNull == null && this.rightOrNull == null) {
+                return block()
+            }
+            return this
+        }
+
         @PublishedApi
         internal fun getTypeHint(value: Any?): String {
             return if (value == null) "null"

mirai-core-utils/src/commonTest/kotlin/net/mamoe/mirai/utils/EitherTest.kt

@@ -1,16 +1,17 @@
 /*
- * Copyright 2019-2021 Mamoe Technologies and contributors.
+ * Copyright 2019-2022 Mamoe Technologies and contributors.
  *
- *  此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
- *  Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
  *
- *  https://github.com/mamoe/mirai/blob/master/LICENSE
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
  */
 
 @file:OptIn(ExperimentalStdlibApi::class)
 
 package net.mamoe.mirai.utils
 
+import net.mamoe.mirai.utils.Either.Companion.flatMapNull
 import net.mamoe.mirai.utils.Either.Companion.fold
 import net.mamoe.mirai.utils.Either.Companion.ifLeft
 import net.mamoe.mirai.utils.Either.Companion.ifRight
@@ -131,6 +132,39 @@ internal class EitherTest {
         )
     }
 
+    @Test
+    fun `can flatMapNull`() {
+        assertTypeIs(typeOf<Either<CharSequence, Int>>(), Either<CharSequence, Int>(1))
+
+        // not null types
+        Either<CharSequence, Int>("left").run {
+            val result = flatMapNull { throw AssertionError("Fail") }
+            assertEquals(this, result) // don't assertSame: arguments boxed separately
+        }
+
+        Either<CharSequence, Int>(1).run {
+            val result = flatMapNull { throw AssertionError("Fail") }
+            assertEquals(this, result) // don't assertSame: arguments boxed separately
+        }
+
+        // nullable types
+        Either<CharSequence, Int?>("left").run {
+            val result = flatMapNull { throw AssertionError("Fail") }
+            assertEquals(this, result) // don't assertSame: arguments boxed separately
+        }
+
+        Either<CharSequence, Int?>(1).run {
+            val result = flatMapNull { throw AssertionError("Fail") }
+            assertEquals(this, result) // don't assertSame: arguments boxed separately
+        }
+
+        // normal case
+        Either<CharSequence, Int?>(null).run {
+            val result = flatMapNull { right(true) } // can interlace type
+            assertEquals(true, result.right)
+        }
+    }
+
     @Test
     fun `can call onRight`() {
         var called = false