✨ New `orNull(Byte)` and `orThrow(Byte)` in `Zero.Companion`

[LVMVRQUXL]

📝 Description

For making usages of the Zero type more expressive, we want to add the orNull(Byte) and orThrow(Byte) experimental methods to the Zero.Companion type, for creating an instance of Zero from the specified number.

Here's the Application Programming Interface (API) goal of this issue:

interface Zero {
    companion object {
        fun orNull(number: Byte): Zero?
        fun orThrow(number: Byte): Zero
    }
}

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

Also, we should deprecate the fromByte and the fromByteOrNull methods from the Zero.Companion experimental type with an error level for using those new factory functions.

✅ Checklist

• [x] ✨ Add the orThrow(Byte) method for Kotlin and Java with tests, documentation and samples.
• [x] ✨ Add the orNull(Byte) method only for Kotlin with tests, documentation and samples.
• [x] 🗑️ Deprecate the fromByteOrNull method with an error level for using the orNull function instead.
• [x] 🗑️ Deprecate the fromByte method with an error level for using the orThrow function instead.
• [x] 📝 Update the unreleased changelog for this issue.
• [x] 📝 Create an issue for removing the factory functions deprecated by this issue.
• [x] 📝 Create an issue for letting the community implementing overloads for these new methods.

[LVMVRQUXL]

Internally, we could use the following pattern for validating inputs: ^[+-]?0+(?:[,.]0+)?$ (try it on RegExr). Here are examples of valid inputs:

0
000000000 // multiple zeros
0.00 // dot as decimal point
0,0000 // comma as decimal point
+0 // unary plus
-0 // unary minus

[LVMVRQUXL]

The pattern used for validating inputs being an essential declaration that consumers should know when calling the factory functions of Zero, it should be part of the public Application Programming Interface (API) with tests, documentation and samples.

[LVMVRQUXL]

The following overloads are not necessary for now, but they could be implemented by the community.

interface Zero {
    companion object {
        fun orNull(number: Short): Zero?
        fun orNull(number: Int): Zero?
        fun orNull(number: Long): Zero?
        fun orNull(number: Float): Zero?
        fun orNull(number: Double): Zero?
        fun orThrow(number: Short): Zero
        fun orThrow(number: Int): Zero
        fun orThrow(number: Long): Zero
        fun orThrow(number: Float): Zero
        fun orThrow(number: Double): Zero
    }
}

See the following issues:

• 716

• 717

• 718

• 719

• 720