✨ New orNull and orThrow functions in StrictlyPositiveInt.Companion type

[LVMVRQUXL]

📝 Description

We want to introduce the orNull and the orThrow experimental factory functions in the StrictlyPositiveInt.Companion type, for creating an instance of StrictlyPositiveInt from the specified number of type Byte, Short, Int, Long, Float or Double.

interface StrictlyPositiveInt {
    companion object {
        fun orNull(number: Byte): StrictlyPositiveInt? = TODO()
        fun orNull(number: Short): StrictlyPositiveInt? = TODO()
        fun orNull(number: Int): StrictlyPositiveInt? = TODO()
        fun orNull(number: Long): StrictlyPositiveInt? = TODO()
        fun orNull(number: Float): StrictlyPositiveInt? = TODO()
        fun orNull(number: Double): StrictlyPositiveInt? = TODO()
        
        fun orThrow(number: Byte): StrictlyPositiveInt = TODO()
        fun orThrow(number: Short): StrictlyPositiveInt = TODO()
        fun orThrow(number: Int): StrictlyPositiveInt = TODO()
        fun orThrow(number: Long): StrictlyPositiveInt = TODO()
        fun orThrow(number: Float): StrictlyPositiveInt = TODO()
        fun orThrow(number: Double): StrictlyPositiveInt = TODO()
    }
}

These factory functions should be available for all platforms, except for the orNull function that shouldn't be accessible from Java, due to its non-explicit support for nullable types.

✅ Checklist

See the Issue implementation section in the contributing guidelines before addressing the following checklist.

• ✨ Add the orThrow(Byte) function for Kotlin and Java with tests, documentation and samples.
• ✨ Add the orNull(Byte) function for Kotlin with tests, documentation and samples.
• ✨ Add the orThrow(Short) function for Kotlin and Java with tests, documentation and samples.
• ✨ Add the orNull(Short) function for Kotlin with tests, documentation and samples.
• ✨ Add the orThrow(Int) function for Kotlin and Java with tests, documentation and samples.
• ✨ Add the orNull(Int) function for Kotlin with tests, documentation and samples.
• ✨ Add the orThrow(Long) function for Kotlin and Java with tests, documentation and samples.
• ✨ Add the orNull(Long) function for Kotlin with tests, documentation and samples.
• ✨ Add the orThrow(Float) function for Kotlin and Java with tests, documentation and samples.
• ✨ Add the orNull(Float) function for Kotlin with tests, documentation and samples.
• ✨ Add the orThrow(Double) function for Kotlin and Java with tests, documentation and samples.
• ✨ Add the orNull(Double) function for Kotlin with tests, documentation and samples.
• 📝 Update the unreleased changelog for this issue.
• 📝 After closing this issue, attach tracking issues to a milestone.

[LVMVRQUXL]

A better alternative of the StrictlyPositiveInt type will be added in the org.kotools.types package (#661), so it is not necessary to add declarations to this type.