✨ Add EmailAddress.Companion.orNull(String, String) (#692)

kotools · Aug 11, 2024 · 34d758a · 34d758a
1 parent dc28988
commit 34d758a
Show file tree

Hide file tree

Showing 4 changed files with 81 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/EmailAddress$Companion {
 	public final synthetic fun fromStringOrNull (Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public final synthetic fun fromStringOrNull (Ljava/lang/Object;Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public final synthetic fun orNull (Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
+	public final synthetic fun orNull (Ljava/lang/String;Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 	public final fun orThrow (Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 	public final fun orThrow (Ljava/lang/String;Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 }

diff --git a/subprojects/library/src/commonMain/kotlin/org/kotools/types/EmailAddress.kt b/subprojects/library/src/commonMain/kotlin/org/kotools/types/EmailAddress.kt
@@ -346,6 +346,37 @@ public class EmailAddress private constructor(private val text: String) {
             null
         }
 
+        /**
+         * Creates an instance of [EmailAddress] from the specified [text].
+         * Returns `null` if the [text] doesn't match the specified [pattern],
+         * or if the [pattern] doesn't match the [default one][PATTERN].
+         *
+         * <br>
+         * <details>
+         * <summary>
+         *     <b>Calling from Kotlin</b>
+         * </summary>
+         *
+         * Here's an example of calling this method from Kotlin code:
+         *
+         * SAMPLE: [org.kotools.types.EmailAddressCompanionCommonSample.orNullStringString]
+         * </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] or [pattern].
+         */
+        @ExperimentalSince(KotoolsTypesVersion.Unreleased)
+        @JvmSynthetic
+        public fun orNull(text: String, pattern: String): EmailAddress? = try {
+            this.orThrow(text, pattern)
+        } catch (exception: IllegalArgumentException) {
+            null
+        }
+
         /**
          * Creates an instance of [EmailAddress] from the specified [text], or
          * throws an [IllegalArgumentException] if the [text] doesn't match the
@@ -413,6 +444,10 @@ public class EmailAddress private constructor(private val text: String) {
          *
          * SAMPLE: [org.kotools.types.EmailAddressCompanionJavaSample.orThrowStringString]
          * </details>
+         * <br>
+         *
+         * See the [orNull] method for returning `null` instead of throwing an
+         * exception in case of invalid [text] or [pattern].
          */
         @ExperimentalSince(KotoolsTypesVersion.Unreleased)
         @JvmStatic

diff --git a/...ts/library/src/commonSample/kotlin/org/kotools/types/EmailAddressCompanionCommonSample.kt b/...ts/library/src/commonSample/kotlin/org/kotools/types/EmailAddressCompanionCommonSample.kt
@@ -62,6 +62,14 @@ class EmailAddressCompanionCommonSample {
         assertNotNull(emailAddress)
     }
 
+    @Test
+    fun orNullStringString() {
+        val text = "[email protected]"
+        val pattern = """^[a-z]+@[a-z]+\.[a-z]+$"""
+        val emailAddress: EmailAddress? = EmailAddress.orNull(text, pattern)
+        assertNotNull(emailAddress)
+    }
+
     @Test
     fun orThrowString() {
         val text = "[email protected]"

diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/EmailAddressTest.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/EmailAddressTest.kt
@@ -265,6 +265,43 @@ class EmailAddressCompanionTest {
         assertNull(actual, message)
     }
 
+    @Test
+    fun orNullStringStringShouldPassWithValidTextAndPattern() {
+        val text: String = Values.VALID
+        val pattern = """^[a-z]+@[a-z]+\.[a-z]+$"""
+        val actual: EmailAddress? = EmailAddress.orNull(text, pattern)
+        val message: String = simpleNameOf<EmailAddress>()
+            .let {
+                "Creating an instance of $it from '$text' with '$pattern' " +
+                        "should pass."
+            }
+        assertNotNull(actual, message)
+    }
+
+    @Test
+    fun orNullStringStringShouldFailWithInvalidText() {
+        val text = "[email protected]"
+        val pattern = """^[a-z]+@[a-z]+\.[a-z]+$"""
+        this.orNullShouldFailWith(text, pattern)
+    }
+
+    @Test
+    fun orNullStringStringShouldFailWithInvalidPattern() {
+        val text: String = Values.VALID
+        val pattern = """^[a-z]+\.[a-z]+$"""
+        this.orNullShouldFailWith(text, pattern)
+    }
+
+    private fun orNullShouldFailWith(text: String, pattern: String) {
+        val actual: EmailAddress? = EmailAddress.orNull(text, pattern)
+        val message: String = simpleNameOf<EmailAddress>()
+            .let {
+                "Creating an instance of $it from '$text' with '$pattern' " +
+                        "should fail."
+            }
+        assertNull(actual, message)
+    }
+
     @Test
     fun orThrowStringShouldPassWithValidText() {
         EmailAddress.orThrow(text = Values.VALID)