✨ Add Zero.Companion.orNull(String) method (#761)

kotools · Jan 9, 2025 · baaea78 · baaea78
1 parent fc5f74b
commit baaea78
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 0 deletions.
diff --git a/subprojects/library/src/api/types.api b/subprojects/library/src/api/types.api
@@ -462,6 +462,7 @@ public final class org/kotools/types/Zero$Companion {
 	public final synthetic fun orNull (F)Lorg/kotools/types/Zero;
 	public final synthetic fun orNull (I)Lorg/kotools/types/Zero;
 	public final synthetic fun orNull (J)Lorg/kotools/types/Zero;
+	public final synthetic fun orNull (Ljava/lang/String;)Lorg/kotools/types/Zero;
 	public final synthetic fun orNull (S)Lorg/kotools/types/Zero;
 	public final fun orThrow (B)Lorg/kotools/types/Zero;
 	public final fun orThrow (D)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
@@ -705,6 +705,39 @@ public class Zero {
             null
         }
 
+        /**
+         * Creates an instance of [Zero] from the specified [text], or returns
+         * `null` if the [text] is an invalid representation of zero.
+         *
+         * The [text] is a valid representation if it matches the following
+         * regular expression: [`^0+(?:\.0+)?$`](https://regexr.com/8arpu).
+         *
+         * <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.orNullWithString]
+         * </details>
+         * <br>
+         *
+         * This method 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 [text].
+         */
+        @ExperimentalSince(KotoolsTypesVersion.V5_0_0)
+        @JvmSynthetic
+        public fun orNull(text: String): Zero? = try {
+            this.orThrow(text)
+        } catch (exception: IllegalArgumentException) {
+            null
+        }
+
         /**
          * Creates an instance of [Zero] from the specified [number], or throws
          * an [IllegalArgumentException] if the [number] is other than zero.
@@ -958,6 +991,10 @@ public class Zero {
          *
          * SAMPLE: [org.kotools.types.ZeroCompanionJavaSample.orThrowWithString]
          * </details>
+         * <br>
+         *
+         * See the [orNull] method for returning `null` instead of throwing an
+         * exception in case of invalid [text].
          */
         @ExperimentalSince(KotoolsTypesVersion.V5_0_0)
         @JvmStatic

diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt
@@ -44,6 +44,13 @@ class ZeroCompanionCommonSample {
         assertNotNull(zero)
     }
 
+    @Test
+    fun orNullWithString() {
+        listOf("0", "000", "0.0", "0.000", "000.0", "000.000")
+            .map(Zero.Companion::orNull)
+            .forEach(::assertNotNull)
+    }
+
     @Test
     fun orThrowWithByte() {
         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
@@ -5,6 +5,7 @@ import kotlin.random.Random
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertFailsWith
+import kotlin.test.assertNotNull
 import kotlin.test.assertNull
 
 @OptIn(ExperimentalKotoolsTypesApi::class)
@@ -62,6 +63,18 @@ class ZeroCompanionTest {
         assertNull(actual)
     }
 
+    @Test
+    fun orNullShouldPassWithValidText(): Unit =
+        sequenceOf("0", "000", "0.0", "0.000", "000.0", "000.000")
+            .map(Zero.Companion::orNull)
+            .forEach(::assertNotNull)
+
+    @Test
+    fun orNullShouldFailWithInvalidText(): Unit =
+        sequenceOf("", " ", ".", "0.", ".0", "abc")
+            .map(Zero.Companion::orNull)
+            .forEach(::assertNull)
+
     @Test
     fun orThrowShouldFailWithByteOtherThanZero() {
         val number: Byte = Byte.randomNonZero()