✨ Add EmailAddress.Companion.orNull(String) function (#635)

kotools · Apr 18, 2024 · 3f209aa · 3f209aa
1 parent d245ebf
commit 3f209aa
Show file tree

Hide file tree

Showing 7 changed files with 114 additions and 15 deletions.
diff --git a/subprojects/library/src/api/types.api b/subprojects/library/src/api/types.api
@@ -449,6 +449,7 @@ public final class org/kotools/types/EmailAddress {
 	public static final fun fromStringOrNull (Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public static final fun fromStringOrNull (Ljava/lang/Object;Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public final fun hashCode ()I
+	public static final fun orNull (Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 	public final fun toString ()Ljava/lang/String;
 }
 
@@ -457,6 +458,7 @@ public final class org/kotools/types/EmailAddress$Companion {
 	public final fun fromString (Ljava/lang/Object;Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public final fun fromStringOrNull (Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public final fun fromStringOrNull (Ljava/lang/Object;Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
+	public final fun orNull (Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 }
 
 public final class org/kotools/types/Zero {

diff --git a/subprojects/library/src/commonMain/kotlin/org/kotools/types/EmailAddress.kt b/subprojects/library/src/commonMain/kotlin/org/kotools/types/EmailAddress.kt
@@ -42,6 +42,10 @@ private const val FINAL_WARNING: String = "RedundantModalityModifier"
  *
  * SAMPLE: EmailAddressJavaSample.constructorString.md
  * </details>
+ * <br>
+ *
+ * You can use the [EmailAddress.Companion.orNull] function for returning `null`
+ * instead of throwing an exception in case of invalid value.
  */
 @ExperimentalKotoolsTypesApi
 @ExperimentalSince(KotoolsTypesVersion.Unreleased)
@@ -365,5 +369,43 @@ public class EmailAddress(private val value: String) {
             return if (valueAsString matches regex) EmailAddress(valueAsString)
             else null
         }
+
+        /**
+         * Creates an instance of [EmailAddress] with the specified [value], or
+         * returns `null` if the [value] doesn't match the
+         * [default pattern][PATTERN].
+         *
+         * <br>
+         * <details open>
+         * <summary>
+         *     <b>Calling from Kotlin</b>
+         * </summary>
+         *
+         * Here's an example of calling this function from Kotlin code:
+         *
+         * SAMPLE: EmailAddressCompanionKotlinSample.orNull_String.md
+         * </details>
+         *
+         * <br>
+         * <details>
+         * <summary>
+         *     <b>Calling from Java</b>
+         * </summary>
+         *
+         * Here's an example of calling this function from Java code:
+         *
+         * SAMPLE: EmailAddressCompanionJavaSample.orNull_String.md
+         * </details>
+         * <br>
+         *
+         * You can use the constructor of [EmailAddress] for throwing an
+         * exception instead of returning `null` in case of invalid [value].
+         */
+        @JvmStatic
+        public fun orNull(value: String): EmailAddress? = try {
+            EmailAddress(value)
+        } catch (exception: IllegalArgumentException) {
+            null
+        }
     }
 }
diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/EmailAddressTest.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/EmailAddressTest.kt
@@ -301,4 +301,46 @@ class EmailAddressCompanionTest {
             EmailAddress.fromStringOrNull(value, pattern)
         assertNull(actual)
     }
+
+    @Test
+    fun orNull_String_should_pass_with_a_valid_value() {
+        val value: String = Values.VALID
+        val actual: EmailAddress? = EmailAddress.orNull(value)
+        assertNotNull(actual)
+    }
+
+    @Test
+    fun orNull_String_should_fail_with_a_missing_at_sign_in_value() {
+        val value: String = Values.MISSING_AT_SIGN
+        this.orNull_String_failingTest(value)
+    }
+
+    @Test
+    fun orNull_String_should_fail_with_a_missing_dot_in_domain_of_value() {
+        val value: String = Values.MISSING_DOMAIN_DOT
+        this.orNull_String_failingTest(value)
+    }
+
+    @Test
+    fun orNull_String_should_fail_with_whitespaces_in_local_part_of_value() {
+        val value: String = Values.WHITESPACES_IN_LOCAL_PART
+        this.orNull_String_failingTest(value)
+    }
+
+    @Test
+    fun orNull_String_should_fail_with_whitespaces_in_domain_first_label_of_value() {
+        val value: String = Values.WHITESPACES_IN_DOMAIN_FIRST_LABEL
+        this.orNull_String_failingTest(value)
+    }
+
+    @Test
+    fun orNull_String_should_fail_with_whitespaces_in_domain_second_label_of_value() {
+        val value: String = Values.WHITESPACES_IN_DOMAIN_SECOND_LABEL
+        this.orNull_String_failingTest(value)
+    }
+
+    private fun orNull_String_failingTest(value: String) {
+        val actual: EmailAddress? = EmailAddress.orNull(value)
+        assertNull(actual)
+    }
 }
diff --git a/subprojects/samples/src/main/java/EmailAddressCompanionJavaSample.java b/subprojects/samples/src/main/java/EmailAddressCompanionJavaSample.java
@@ -42,4 +42,9 @@ void fromStringOrNull_Any_Any() {
                 EmailAddress.fromStringOrNull(value, pattern); // TABS: 1
         System.out.println(address != null); // true
     } // END
+
+    void orNull_String() {
+        final EmailAddress address = EmailAddress.orNull("[email protected]");
+        System.out.println(address != null); // true
+    } // END
 }
diff --git a/subprojects/samples/src/main/kotlin/EmailAddressCompanionKotlinSample.kt b/subprojects/samples/src/main/kotlin/EmailAddressCompanionKotlinSample.kt
@@ -43,4 +43,10 @@ internal object EmailAddressCompanionKotlinSample {
             EmailAddress.fromStringOrNull(value, pattern) // TABS: 1
         println(address != null) // true
     } // END
+
+    @Suppress("FunctionName")
+    fun orNull_String() {
+        val address: EmailAddress? = EmailAddress.orNull("[email protected]")
+        println(address != null) // true
+    } // END
 }
diff --git a/subprojects/samples/src/test/java/EmailAddressCompanionJavaSampleTest.java b/subprojects/samples/src/test/java/EmailAddressCompanionJavaSampleTest.java
@@ -3,41 +3,39 @@
 import org.junit.jupiter.api.Test;
 
 class EmailAddressCompanionJavaSampleTest {
+    private final EmailAddressCompanionJavaSample sample =
+            new EmailAddressCompanionJavaSample();
+
     @Test
     void patternSample_should_pass() {
-        final EmailAddressCompanionJavaSample sample =
-                new EmailAddressCompanionJavaSample();
         final String expected = "^\\S+@\\S+\\.\\S+$";
-        Assert.prints(expected, sample::patternSample);
+        Assert.prints(expected, this.sample::patternSample);
     }
 
     @Test
     void fromString_Any_should_pass() {
-        final EmailAddressCompanionJavaSample sample =
-                new EmailAddressCompanionJavaSample();
         final String expected = "success";
-        Assert.prints(expected, sample::fromString_Any);
+        Assert.prints(expected, this.sample::fromString_Any);
     }
 
     @Test
     void fromString_Any_Any_should_pass() {
-        final EmailAddressCompanionJavaSample sample =
-                new EmailAddressCompanionJavaSample();
         final String expected = "success";
-        Assert.prints(expected, sample::fromString_Any_Any);
+        Assert.prints(expected, this.sample::fromString_Any_Any);
     }
 
     @Test
     void fromStringOrNull_Any_should_pass() {
-        final EmailAddressCompanionJavaSample sample =
-                new EmailAddressCompanionJavaSample();
-        Assert.printsTrue(sample::fromStringOrNull_Any);
+        Assert.printsTrue(this.sample::fromStringOrNull_Any);
     }
 
     @Test
     void fromStringOrNull_Any_Any_should_pass() {
-        final EmailAddressCompanionJavaSample sample =
-                new EmailAddressCompanionJavaSample();
-        Assert.printsTrue(sample::fromStringOrNull_Any_Any);
+        Assert.printsTrue(this.sample::fromStringOrNull_Any_Any);
+    }
+
+    @Test
+    void orNull_String_should_pass() {
+        Assert.printsTrue(this.sample::orNull_String);
     }
 }
diff --git a/subprojects/samples/src/test/kotlin/EmailAddressCompanionKotlinSampleTest.kt b/subprojects/samples/src/test/kotlin/EmailAddressCompanionKotlinSampleTest.kt
@@ -26,4 +26,8 @@ class EmailAddressCompanionKotlinSampleTest {
     fun `fromStringOrNull(Any, Any) should pass`(): Unit = assertPrintsTrue(
         EmailAddressCompanionKotlinSample::fromStringOrNull_Any_Any
     )
+
+    @Test
+    fun `orNull(String) should pass`(): Unit =
+        assertPrintsTrue(EmailAddressCompanionKotlinSample::orNull_String)
 }