✨ New PositiveInteger type

[LVMVRQUXL]

📝 Description

We want to introduce the PositiveInteger experimental type, in the org.kotools.types package of the types subproject, for representing an integer that is greater than zero, with the following Application Programming Interface (API):

interface PositiveInteger {
    override fun equals(other: Any?): Boolean
    override fun hashCode(): Int
    override fun toString(): String
    companion object {
        const val PATTERN: String
        fun orNull(number: Any): PositiveInteger?
        fun orThrow(number: Any): PositiveInteger
        fun random(): PositiveInteger
    }
}

This type should be available for all Kotlin platforms and Java.

The pattern used for validating inputs should be: ^\+?[1-9]\d*$.
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.
• \+ Escaped character. Matches a "+" character (char code 43).
• ? Quantifier. Match between 0 and 1 of the preceding token.
• [] Character set. Matches any character in the set.
• 1-9 Range. Matches a character in the range "1" to "9" (char code 49 to 57). Case sensitive.
• \d Digit. Matches any digit character (0-9).
• * Quantifier. Match 0 or more of the preceding token.
• $ End. Matches the end of the string, or the end of a line if the multiline flag (m) is enabled.

✅ Checklist

• ✨ Add the type with documentation.
• ✨ Add the PATTERN property with tests, documentation and samples.
• ✨ Add the orThrow(Any) function with tests, documentation and samples.
• ✨ Add the orNull(Any) function with tests, documentation and samples.
• ✨ Add the random() function with tests, documentation and samples.
• ✨ Add the structural equality operations (equals(Any?) and hashCode() functions) with tests, documentation and samples.
• ✨ Add the toString() function with tests, documentation and samples.
• 📝 Update the unreleased changelog for this issue.

[LVMVRQUXL]

The PositiveInteger.Companion.random() function should use the widest range available, like the Long type's range, for producing a random value.