Static builders named of

[LVMVRQUXL]

🤔 The problem

Today, we provide type converters for creating types (e.g. toNotBlankString).
This approach brings the two following problems:

1. A function that should concern only the required type is attached to the input type. For instance, the toNonZeroInt function is attached to the Number type for converting it to NonZeroInt. The word converting is important here because for users it looks like a conversion instead of creating a type wrapping the original number.
2. It clutters the documentation by having the required type and the type converter separated, which makes indirections on where to look when having a lot of types (this is the case for the kotools.types.number package).

💡 The idea

The idea is to introduce static builders named of in the companion object of each type for creating their instances.
Here's an example for the PositiveInt type:

fun PositiveInt.Companion.of(number: Int): PositiveInt? {
    TODO("Not yet implemented")
}

fun main() {
    var x: PositiveInt? = PositiveInt.of(10L)
    println(x) // 10
    x = PositiveInt.of(-2)
    println(x) // null
}

For improving the documentation discovery and reducing the noise in it, we should define these static builders as member functions instead of extension functions.

Thanks to polymorphism, the return type of these functions could variate depending on their input type. Here's our strategy:

• if the input is valid, we should return the intended type
• if the input is invalid, we should return null.

/** Converts the given [number] to a [PositiveInt]. */
fun PositiveInt.Companion.of(number: StrictlyPositiveInt): PositiveInt {
    TODO("Not yet implemented")
}

✅ Checklist

Here's the checklist to address for implementing this idea:

• Add an experimental static builder named of for all types.
• Stabilize the static builders named of for all types.

🙏 Help needed

Please give this post a reaction if you are interested in this change and comment below your thoughts on it.
We would love to have your feedback!

[LVMVRQUXL]

This idea is duplicated by #315.