✨ New `EmailAddress` type

[LVMVRQUXL]

📝 Description

We would like to introduce an experimental type named EmailAddress for all platforms with the following minimum API:

@Serializable
interface EmailAddress {
    companion object {
        val regex: Regex
        fun create(text: String): EmailAddress
        fun createOrNull(text: String): EmailAddress?
    }

    override fun equals(other: Any?): Boolean
    override fun hashCode(): Int
    override fun toString(): String
}

This type should be serializable as String.
Being experimental, the properties and functions of this type shouldn't be available yet for Java users.

✅ Checklist

• Add type with the declarations of Companion and the function toString(), test them, update the public API binaries and the unreleased changelog.
• Override the functions equals(Any?) and hashCode(), test them and update public API binaries.
• Make the type serializable, test its serialization and deserialization, then update the public API binaries.
• Create an issue for making the declarations of this type available for Java users in the next patch release.
• Create an issue for adding an experimental property length: StrictlyPositiveInt to this type.
• Create an issue template for introducing an experimental declaration. There is no need to attach this issue to the corresponding commit.
• Create an issue for adding an experimental property domain: WebDomain to this type.
• Create an issue for adding an experimental function toNotBlankString(): NotBlankString to this type.
• Treat all comments of this issue.
• Resolve comment ✨ New EmailAddress type #339 (comment).
• Resolve comment ✨ New EmailAddress type #339 (comment).
• Resolve comment ✨ New EmailAddress type #339 (comment).
• Resolve comment ✨ New EmailAddress type #339 (comment).
• Remove the JvmField annotation on the EmailAddress.Companion.regex property.
• Refactor the serializer of this type (hint: centralize the serialization as String).
• Apply these changes to the release/4.4.0 branch.
• Close this issue and update the status of tracking issues.

[LVMVRQUXL]

Here's another interesting way of creating an instance of EmailAddress:

val email: EmailAddress = "contact" at "example.com"
println(email) // contact@example.com

[LVMVRQUXL]

At the end of the checklist, we should add the creation of issues for the following declarations:

• localPart property representing the local part of the email address
• domain: WebDomain property representing the domain of the email address
• length: StrictlyPositiveInt returning the number of characters contained in the email address.

[LVMVRQUXL]

Here's a complete regular expression for validating email addresses: ^([a-zA-Z]+\d*(?:[-_\.][a-zA-Z\d]+)*)@([a-z]+(?:[-_][a-z]+)*\.[a-z]+(?:[-_][a-z]+)*)$.

[LVMVRQUXL]

A factory function may be introduced for returning a domain-based object representing different type of errors indicating if their is a problem in the local part or in the domain.

sealed interface EmailAddressCreationResult
interface ValidEmailAddress : EmailAddressCreationResult
interface InvalidLocalPart : EmailAddressCreationResult
interface InvalidDomain : EmailAddressCreationResult

[LVMVRQUXL]

Regular expression for email addresses, v2: ^([a-z](?:[-_\.]?[a-z\d]+)*)@([a-z]+(?:[-_][a-z]+)*\.[a-z]+(?:[-_][a-z]+)*)$.