✨ New factory functions for `EmailAddress` accepting a custom regular expression

[LVMVRQUXL]

📝 Description

Like documented in #586 (comment), we would like to introduce the following experimental factory functions in the EmailAddress type for accepting a custom regular expression:

fun EmailAddress.Companion.create(text: String, regex: Regex): EmailAddress
fun EmailAddress.Companion.createOrNull(text: String, regex: Regex): EmailAddress?

The specified regex should match the pattern used in the default regular expression.

val result: Boolean = "^[a-z]+@[a-z]+\\.[a-z]+$" matches Regex("^\\S+@\\S+\\.\\S+$")
println(result) // true

Here are some examples of calling these functions from Kotlin code:

EmailAddress.create("contact@kotools.org") // passes using the default regular expression
EmailAddress.create(" @kotools.org") // fails using the default regular expression

val regex = Regex("^[a-z]+@[a-z]+\\.[a-z]+$")
EmailAddress.create("contact@kotools.org", regex) // passes using the specified regular expression
EmailAddress.create(" @kotools.org") // fails using the specified regular expression

The Regex type being unavailable on Java, these functions shouldn't be available on that platform.

✅ Checklist

• Add the EmailAddress.Companion.create(String, Regex) function, test its behavior with Kotlin, update the public API binaries and update the unreleased changelog.
• Add the EmailAddress.Companion.createOrNull(String, Regex) function, test its behavior with Kotlin, update the public API binaries and update the unreleased changelog.
• Close this issue as completed and update tracking ones if present.

[LVMVRQUXL]

This issue is not ready to implement and needs more design thinking.