✨ New `PositiveInt` type in `org.kotools.types` package

[LVMVRQUXL]

📝 Description

We want to introduce a PositiveInt experimental type, in the org.kotools.types package of the types Gradle subproject, for representing an integer of type Int that is greater than zero. This type should be serializable as Int.

Here's the Application Programming Interface (API) goal for this type:

// In 'types' Gradle subproject:
interface PositiveInt {
    override fun equals(other: Any?): Boolean
    override fun hashCode(): Int
    fun toInt(): Int
    override fun toString(): String
    
    companion object {
        val min: PositiveInt
        val max: PositiveInt
        
        fun fromInt(number: Int): PositiveInt = TODO()
        fun fromIntOrNull(number: Int): PositiveInt? = TODO()
        
        fun random(): PositiveInt
    }
}

// In 'types-kotlinx-serialization' Gradle subproject:
val KotoolsTypesSerializers.positiveInt: SerializersModule

🔗 Dependencies

This issue is blocked by the following ones:

• [x] #650

✅ Checklist

• [ ] ✨ Add the type with a private constructor and documentation.
• [ ] ✨ Add the fromIntOrNull(Int) function with tests, documentation and samples.
• [ ] ✨ Add the fromInt(Int) function with tests, documentation and samples.
• [ ] ✨ Add the toInt() function with tests, documentation and samples.
• [ ] ✨ Add the toString() function with tests, documentation and samples.
• [ ] ✨ Add structural equality operations (equals(Any?) and hashCode() functions) with tests, documentation and samples.
• [ ] ✨ Add the min property with tests, documentation and samples.
• [ ] ✨ Add the max property with tests, documentation and samples.
• [ ] ✨ Add the random() function with tests, documentation and samples.
• [ ] ✨ Add the KotoolsTypesSerializers.positiveInt property for making this type serializable as Int.
• [ ] 📝 Add an entry for this issue in the unreleased changelog.
• [ ] 📝 Create an issue for introducing additional conversions with Byte and Short types.
• [ ] 💬 Resolve comments of this issue.

[LVMVRQUXL]

In the future, we could make instances of this type comparable with themselves and the integer types from the Kotlin standard library.

interface PositiveInt : Comparable<PositiveInteger> {
    operator fun compareTo(other: Byte): Int
    operator fun compareTo(other: Short): Int
    operator fun compareTo(other: Int): Int
    operator fun compareTo(other: Long): Int
    operator fun compareTo(other: PositiveInteger): Int
}

[LVMVRQUXL]

In the future, we could add support for basic arithmetic operations +, -, *, / and %.

[LVMVRQUXL]

In the future, we could provide additional conversions for the PositiveInt.

interface PositiveInt {
    fun toByte(): Byte
    fun toShort(): Short
    fun toLong(): Long
    fun toFloat(): Float
    fun toDouble(): Double
}

[LVMVRQUXL]

In the future, we could introduce types representing the digits 1, 2, 3, 4, 5, 6, 7, 8 and 9. The digit 0 is already represented by the Zero experimental type in the org.kotools.types package.

It may also be interesting to move types related to digits in a new org.kotools.types.digit package.

[LVMVRQUXL]

This type will be implemented internally for the PositiveInteger type (see issue #661).