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

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

Hide file tree

Showing 5 changed files with 85 additions and 0 deletions.
diff --git a/subprojects/library/src/api/types.api b/subprojects/library/src/api/types.api
@@ -444,6 +444,7 @@ public final class org/kotools/types/Zero {
 	public static final fun orThrow (F)Lorg/kotools/types/Zero;
 	public static final fun orThrow (I)Lorg/kotools/types/Zero;
 	public static final fun orThrow (J)Lorg/kotools/types/Zero;
+	public static final fun orThrow (Ljava/lang/String;)Lorg/kotools/types/Zero;
 	public static final fun orThrow (S)Lorg/kotools/types/Zero;
 	public final fun toByte ()B
 	public final fun toChar ()C
@@ -467,6 +468,7 @@ public final class org/kotools/types/Zero$Companion {
 	public final fun orThrow (F)Lorg/kotools/types/Zero;
 	public final fun orThrow (I)Lorg/kotools/types/Zero;
 	public final fun orThrow (J)Lorg/kotools/types/Zero;
+	public final fun orThrow (Ljava/lang/String;)Lorg/kotools/types/Zero;
 	public final fun orThrow (S)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
@@ -928,5 +928,45 @@ public class Zero {
             require(number == 0.0) { InvalidZero(number) }
             return Zero()
         }
+
+        /**
+         * Creates an instance of [Zero] from the specified [text], or throws an
+         * [IllegalArgumentException] 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.orThrowWithString]
+         * </details>
+         *
+         * <br>
+         * <details>
+         * <summary>
+         *     <b>Calling from Java</b>
+         * </summary>
+         *
+         * Here's an example of calling this method from Java code:
+         *
+         * SAMPLE: [org.kotools.types.ZeroCompanionJavaSample.orThrowWithString]
+         * </details>
+         */
+        @ExperimentalSince(KotoolsTypesVersion.V5_0_0)
+        @JvmStatic
+        public fun orThrow(text: String): Zero {
+            val regex = Regex("""^0+(?:\.0+)?$""")
+            require(text matches regex) {
+                "'$text' is not a valid representation of zero."
+            }
+            return Zero()
+        }
     }
 }
diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt
@@ -111,4 +111,16 @@ class ZeroCompanionCommonSample {
         }
         assertTrue(isSuccess)
     }
+
+    @Test
+    fun orThrowWithString() {
+        val isSuccess: Boolean = try {
+            listOf("0", "000", "0.0", "0.000", "000.0", "000.000")
+                .forEach(Zero.Companion::orThrow)
+            true
+        } catch (exception: IllegalArgumentException) {
+            false
+        }
+        assertTrue(isSuccess)
+    }
 }
diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt
@@ -114,6 +114,22 @@ class ZeroCompanionTest {
         assertFailsWith<IllegalArgumentException> { Zero.orThrow(number) }
             .assertIsInvalidZero(number)
     }
+
+    @Test
+    fun orThrowShouldPassWithValidText(): Unit =
+        listOf("0", "000", "0.0", "0.000", "000.0", "000.000")
+            .forEach(Zero.Companion::orThrow)
+
+    @Test
+    fun orThrowShouldFailWithInvalidText(): Unit =
+        listOf("", " ", ".", "0.", ".0", "abc")
+            .forEach {
+                val exception: IllegalArgumentException =
+                    assertFailsWith { Zero.orThrow(it) }
+                val actual: String? = exception.message
+                val expected = "'$it' is not a valid representation of zero."
+                assertEquals(expected, actual)
+            }
 }
 
 // ----------------------------- Number extensions -----------------------------

diff --git a/subprojects/library/src/jvmTest/java/org/kotools/types/ZeroCompanionJavaSample.java b/subprojects/library/src/jvmTest/java/org/kotools/types/ZeroCompanionJavaSample.java
@@ -3,6 +3,8 @@
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
 
+import java.util.Arrays;
+
 @SuppressWarnings("NewClassNamingConvention")
 class ZeroCompanionJavaSample {
     @Test
@@ -82,4 +84,17 @@ void orThrowWithDouble() {
         }
         Assertions.assertTrue(isSuccess);
     }
+
+    @Test
+    void orThrowWithString() {
+        boolean isSuccess;
+        try {
+            Arrays.asList("0", "000", "0.0", "0.000", "000.0", "000.000")
+                    .forEach(Zero::orThrow);
+            isSuccess = true;
+        } catch (final IllegalArgumentException exception) {
+            isSuccess = false;
+        }
+        Assertions.assertTrue(isSuccess);
+    }
 }