✨ Add Zero.Companion.orNull(Byte) method (#688)

kotools · Aug 1, 2024 · 8dceb96 · 8dceb96
1 parent e4a2645
commit 8dceb96
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 0 deletions.
diff --git a/subprojects/library/src/api/types.api b/subprojects/library/src/api/types.api
@@ -469,6 +469,7 @@ public final class org/kotools/types/Zero {
 public final class org/kotools/types/Zero$Companion {
 	public final fun fromByte (B)Lorg/kotools/types/Zero;
 	public final synthetic fun fromByteOrNull (B)Lorg/kotools/types/Zero;
+	public final synthetic fun orNull (B)Lorg/kotools/types/Zero;
 	public final fun orThrow (B)Lorg/kotools/types/Zero;
 }
 
diff --git a/subprojects/library/src/commonMain/kotlin/org/kotools/types/Zero.kt b/subprojects/library/src/commonMain/kotlin/org/kotools/types/Zero.kt
@@ -591,6 +591,36 @@ public class Zero {
             null
         }
 
+        /**
+         * Creates an instance of [Zero] from the specified [number], or returns
+         * `null` if the [number] is other than zero.
+         *
+         * <br>
+         * <details>
+         * <summary>
+         *     <b>Calling from Kotlin</b>
+         * </summary>
+         *
+         * Here's an example of calling this method from Kotlin code:
+         *
+         * SAMPLE: [org.kotools.types.ZeroCompanionCommonSample.orNull]
+         * </details>
+         * <br>
+         *
+         * This function is not available from Java code due to its non-explicit
+         * [support for nullable types](https://kotlinlang.org/docs/java-to-kotlin-nullability-guide.html#support-for-nullable-types).
+         *
+         * See the [orThrow] method for throwing an exception instead of
+         * returning `null` in case of invalid [number].
+         */
+        @ExperimentalSince(KotoolsTypesVersion.Unreleased)
+        @JvmSynthetic
+        public fun orNull(number: Byte): Zero? = try {
+            this.orThrow(number)
+        } catch (exception: IllegalArgumentException) {
+            null
+        }
+
         /**
          * Creates an instance of [Zero] from the specified [number], or throws
          * an [IllegalArgumentException] if the [number] is other than zero.
@@ -616,6 +646,10 @@ public class Zero {
          *
          * SAMPLE: [org.kotools.types.ZeroCompanionJavaSample.orThrow]
          * </details>
+         * <br>
+         *
+         * See the [orNull] method for returning `null` instead of throwing an
+         * exception in case of invalid [number].
          */
         @ExperimentalSince(KotoolsTypesVersion.Unreleased)
         @JvmStatic

diff --git a/subprojects/library/src/commonSample/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt b/subprojects/library/src/commonSample/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt
@@ -26,6 +26,13 @@ class ZeroCompanionCommonSample {
         assertNotNull(zero)
     }
 
+    @Test
+    fun orNull() {
+        val number: Byte = 0
+        val zero: Zero? = Zero.orNull(number)
+        assertNotNull(zero)
+    }
+
     @Test
     fun orThrow() {
         val number: Byte = 0

diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt
@@ -48,6 +48,23 @@ class ZeroCompanionTest {
         assertNull(actual)
     }
 
+    @Test
+    fun orNullShouldPassWithByteThatEqualsZero() {
+        val number: Byte = 0
+        val actual: Zero? = Zero.orNull(number)
+        assertNotNull(actual)
+    }
+
+    @Test
+    fun orNullShouldFailWithByteOtherThanZero() {
+        val number: Byte = setOf(Byte.MIN_VALUE..-1, 1..Byte.MAX_VALUE)
+            .random()
+            .random()
+            .toByte()
+        val actual: Zero? = Zero.orNull(number)
+        assertNull(actual)
+    }
+
     @Test
     fun orThrowShouldPassWithByteThatEqualsZero() {
         val number: Byte = 0