Aligning factory functions with Java & Kotlin standards

[LVMVRQUXL]

🤔 The problem

The current stable API provides factory functions encapsulating their result in a Result type.
This is for example the case for the toNonZeroInt factory function:

/**
 * Returns this number as an encapsulated NonZeroInt, which may involve
 * rounding or truncation, or returns an encapsulated IllegalArgumentException
 * if this number equals zero.
 */
fun Int.toNonZeroInt(): Result<NonZeroInt>

But this practice increases the complexity of the API by using a concept that is not widely accepted in the Kotlin community.

Also, the current factory functions being declared as public extension functions, they pollute the API and are not scoped within their context in the API reference.

💡 The idea

For improving our representation of a possible failure, Kotools Types should represent them with the null expression, modeling an absence of value in Java and Kotlin.

Also, the factory functions should be provided in the companion object of the target type.
Here's an example for the NonZeroInt type:

interface NonZeroInt {
    companion object {
        fun createOrNull(value: Int): NonZeroInt? = TODO()
    }
}

Finally, factory functions of the library should have the following naming conventions:

• create - creates an instance of a given type from the specified input.
• createOrNull - creates an instance of a given type from the specified input, or returns null if the input is invalid.

✅ Checklist

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

• New factory functions named create* for all types #316
• Deletion of factory functions suffixed by OrNull or OrThrow #258
• Stabilization of factory functions named create* for stable types #321
• Deprecation of factory functions using Result #263
• Deprecation promotion of factory functions using Result to error level #265
• Deprecation promotion of factory functions using Result to hidden level #266
• Deletion of factory functions using Result #267
• Deprecation of ResultContext #264
• Deprecation promotion of ResultContext to error level #268
• Deprecation promotion of ResultContext to hidden level #269
• Deletion of ResultContext #270

🙏 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 duplicates the one discussed in #297.

[LVMVRQUXL]

The name create is also a good candidate for naming factory functions, because their create an instance of a given type and encapsulate the idea behind the of and the from naming conventions.
Factory functions should have the following name:

• create if the logic shouldn't fail
• createOrNull if the logic can fail.

[LVMVRQUXL]

Another good alternative is to use the following convention for creating objects:

• T(input): T constructor if the creation logic shouldn't fail
• T.orNull(input): T? factory function if the logic can fail.

Here's an example for the NotBlankString type:

private fun main() {
    val value = "Hello world"
    val text: NotBlankString = NotBlankString.orNull(value)
        ?: error("String shouldn't be blank")
    println(text) // Hello world
}

/** Represents a string having at least one character, excluding whitespaces. */
public class NotBlankString private constructor(private val value: String) {
    init {
        require(value.isNotBlank()) {
            "String shouldn't be blank"
        }
    }

    /** Returns this string as [String]. */
    override fun toString(): String = value

    /** Contains static declarations for the [NotBlankString] type. */
    public companion object {
        /**
         * Creates an instance of [NotBlankString] with the specified [value],
         * or returns `null` if the [value] is [blank][CharSequence.isBlank].
         */
        public fun orNull(value: CharSequence): NotBlankString? =
            if (value.isBlank()) null
            else NotBlankString("$value")
    }
}

[LVMVRQUXL]

This is the best design for explicitness.

[LVMVRQUXL]

This idea is duplicated by #335.