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

subprojects/library/src/api/types.api

@@ -434,6 +434,7 @@ public final class org/kotools/types/EmailAddress {
 	public static final fun fromString (Ljava/lang/Object;Ljava/lang/Object;)Lorg/kotools/types/EmailAddress;
 	public final fun hashCode ()I
 	public static final fun orThrow (Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
+	public static final fun orThrow (Ljava/lang/String;Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 	public final fun toString ()Ljava/lang/String;
 }
 
@@ -443,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 fun orThrow (Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
+	public final fun orThrow (Ljava/lang/String;Ljava/lang/String;)Lorg/kotools/types/EmailAddress;
 }
 
 public final class org/kotools/types/Zero {

subprojects/library/src/commonMain/kotlin/org/kotools/types/EmailAddress.kt

@@ -350,5 +350,48 @@ public class EmailAddress private constructor(private val text: String) {
             require(text matches regex) { InvalidEmailAddress(text, pattern) }
             return EmailAddress(text)
         }
+
+        /**
+         * Creates an instance of [EmailAddress] from the specified [text].
+         * Throws an [IllegalArgumentException] 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.orThrowStringString]
+         * </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.EmailAddressCompanionJavaSample.orThrowStringString]
+         * </details>
+         */
+        @ExperimentalSince(KotoolsTypesVersion.Unreleased)
+        @JvmStatic
+        public fun orThrow(text: String, pattern: String): EmailAddress {
+            val validationPattern: String = this.PATTERN
+            val patternRegex = Regex(validationPattern)
+            require(pattern matches patternRegex) {
+                InvalidEmailAddressPattern(pattern, validationPattern)
+            }
+            val textRegex = Regex(pattern)
+            require(text matches textRegex) {
+                InvalidEmailAddress(text, pattern)
+            }
+            return EmailAddress(text)
+        }
     }
 }

subprojects/library/src/commonSample/kotlin/org/kotools/types/EmailAddressCompanionCommonSample.kt

@@ -66,4 +66,17 @@ class EmailAddressCompanionCommonSample {
         }
         assertTrue(isSuccess)
     }
+
+    @Test
+    fun orThrowStringString() {
+        val text = "[email protected]"
+        val pattern = """^[a-z]+@[a-z]+\.[a-z]+$"""
+        val isSuccess: Boolean = try {
+            EmailAddress.orThrow(text, pattern)
+            true
+        } catch (exception: IllegalArgumentException) {
+            false
+        }
+        assertTrue(isSuccess)
+    }
 }

subprojects/library/src/commonTest/kotlin/org/kotools/types/EmailAddressTest.kt

@@ -263,4 +263,39 @@ class EmailAddressCompanionTest {
         ).toString()
         assertEquals(expected, actual)
     }
+
+    @Test
+    fun orThrowStringStringShouldPassWithValidTextAndPattern() {
+        val text: String = Values.VALID
+        val pattern = """^[a-z]+@[a-z]+\.[a-z]+$"""
+        EmailAddress.orThrow(text, pattern)
+    }
+
+    @Test
+    fun orThrowStringStringShouldFailWithInvalidText() {
+        val text = "[email protected]"
+        val pattern = """^[a-z]+@[a-z]+\.[a-z]+$"""
+        val exception: IllegalArgumentException = assertFailsWith {
+            EmailAddress.orThrow(text, pattern)
+        }
+        val actual: String? = exception.message
+        val expected: String = InvalidEmailAddress(text, pattern)
+            .toString()
+        assertEquals(expected, actual)
+    }
+
+    @Test
+    fun orThrowStringStringShouldFailWithInvalidPattern() {
+        val text: String = Values.VALID
+        val pattern = """^[a-z]+\.[a-z]+$"""
+        val exception: IllegalArgumentException = assertFailsWith {
+            EmailAddress.orThrow(text, pattern)
+        }
+        val actual: String? = exception.message
+        val expected: String = InvalidEmailAddressPattern(
+            pattern,
+            validationPattern = EmailAddress.PATTERN
+        ).toString()
+        assertEquals(expected, actual)
+    }
 }

subprojects/library/src/jvmSample/java/org/kotools/types/EmailAddressCompanionJavaSample.java

@@ -51,4 +51,18 @@ void orThrowString() {
         }
         Assertions.assertTrue(isSuccess);
     }
+
+    @Test
+    void orThrowStringString() {
+        final String text = "[email protected]";
+        final String pattern = "^[a-z]+@[a-z]+\\.[a-z]+$";
+        boolean isSuccess;
+        try {
+            EmailAddress.orThrow(text, pattern);
+            isSuccess = true;
+        } catch (final IllegalArgumentException exception) {
+            isSuccess = false;
+        }
+        Assertions.assertTrue(isSuccess);
+    }
 }