✨ Add EmailAddress.Companion.PATTERN constant property (#635)

Adds the constant property with tests, tested Kotlin and Java code samples, and dumps the Application Binary Interface (ABI).

src/api/types.api

@@ -441,6 +441,11 @@ public final class kotools/types/web/EmailAddress$Companion {
 }
 
 public final class org/kotools/types/EmailAddress {
+	public static final field Companion Lorg/kotools/types/EmailAddress$Companion;
+	public static final field PATTERN Ljava/lang/String;
+}
+
+public final class org/kotools/types/EmailAddress$Companion {
 }
 
 public final class org/kotools/types/Zero {

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

@@ -11,4 +11,48 @@ import kotools.types.internal.KotoolsTypesVersion
 @ExperimentalKotoolsTypesApi
 @ExperimentalSince(KotoolsTypesVersion.Unreleased)
 @OptIn(InternalKotoolsTypesApi::class)
-public class EmailAddress private constructor()
+public class EmailAddress private constructor() {
+    /** Contains static declarations for the [EmailAddress] type. */
+    public companion object {
+        /**
+         * The pattern that an email address should match.
+         *
+         * The underlying pattern is `^\S+@\S+\.\S+$`.
+         *
+         * Here's the explanation associated to each symbol used in this
+         * pattern:
+         * - `^` **Beginning.** Matches the beginning of the string, or the
+         * beginning of a line if the multiline flag (m) is enabled.
+         * - `\S` **Not whitespace.** Matches any character that is not a
+         * whitespace character (spaces, tabs, line breaks).
+         * - `+` **Quantifier.** Match 1 or more of the preceding token.
+         * - `@` **Character.** Match a "@" character (char code 64).
+         * - `\.` **Escaped character.** Matches a "." character (char code 46).
+         * - `$` **End.** Matches the end of the string, or the end of a line if
+         * the multiline flag (m) is enabled.
+         *
+         * <br>
+         * <details open>
+         * <summary>
+         *     <b>Calling from Kotlin</b>
+         * </summary>
+         *
+         * Here's an example of calling this function from Kotlin code:
+         *
+         * SAMPLE: EmailAddressCompanionKotlinSample.patternSample.md
+         * </details>
+         *
+         * <br>
+         * <details>
+         * <summary>
+         *     <b>Calling from Java</b>
+         * </summary>
+         *
+         * Here's an example of calling this function from Java code:
+         *
+         * SAMPLE: EmailAddressCompanionJavaSample.patternSample.md
+         * </details>
+         */
+        public const val PATTERN: String = "^\\S+@\\S+\\.\\S+\$"
+    }
+}

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

@@ -0,0 +1,15 @@
+package org.kotools.types
+
+import kotools.types.experimental.ExperimentalKotoolsTypesApi
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+@OptIn(ExperimentalKotoolsTypesApi::class)
+class EmailAddressCompanionTest {
+    @Test
+    fun pattern_should_pass() {
+        val actual: String = EmailAddress.PATTERN
+        val expected = "^\\S+@\\S+\\.\\S+\$"
+        assertEquals(expected, actual)
+    }
+}

subprojects/samples/src/main/java/EmailAddressCompanionJavaSample.java

@@ -0,0 +1,8 @@
+package org.kotools.types;
+
+class EmailAddressCompanionJavaSample {
+    void patternSample() {
+        final String pattern = EmailAddress.PATTERN;
+        System.out.println(pattern); // ^\S+@\S+\.\S+$
+    }
+}

subprojects/samples/src/main/kotlin/EmailAddressCompanionKotlinSample.kt

@@ -0,0 +1,11 @@
+package org.kotools.types
+
+import kotools.types.experimental.ExperimentalKotoolsTypesApi
+
+internal object EmailAddressCompanionKotlinSample {
+    @OptIn(ExperimentalKotoolsTypesApi::class)
+    fun patternSample() {
+        val pattern: String = EmailAddress.PATTERN
+        println(pattern) // ^\S+@\S+\.\S+$
+    }
+}

subprojects/samples/src/test/java/EmailAddressCompanionJavaSampleTest.java

@@ -0,0 +1,18 @@
+package org.kotools.types;
+
+import com.github.stefanbirkner.systemlambda.SystemLambda;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+class EmailAddressCompanionJavaSampleTest {
+    @Test
+    void patternSample_should_pass() {
+        final EmailAddressCompanionJavaSample sample =
+                new EmailAddressCompanionJavaSample();
+        final String actual = Assertions.assertDoesNotThrow(
+                () -> SystemLambda.tapSystemOut(sample::patternSample).trim()
+        );
+        final String expected = "^\\S+@\\S+\\.\\S+$";
+        Assertions.assertEquals(expected, actual);
+    }
+}

subprojects/samples/src/test/kotlin/EmailAddressCompanionKotlinSampleTest.kt

@@ -0,0 +1,16 @@
+package org.kotools.types
+
+import com.github.stefanbirkner.systemlambda.SystemLambda
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class EmailAddressCompanionKotlinSampleTest {
+    @Test
+    fun patternSample_should_pass() {
+        val actual: String = SystemLambda
+            .tapSystemOut(EmailAddressCompanionKotlinSample::patternSample)
+            .trim()
+        val expected = "^\\S+@\\S+\\.\\S+\$"
+        assertEquals(expected, actual)
+    }
+}