💡 The `create` and `createOrNull` factory functions #587

LVMVRQUXL · 2024-03-17T12:23:39Z

📝 Description

Originally discussed in #335.

We would like to redesign our factory functions by introducing new create and createOrNull factory functions for creating our stable types with the following behavior:

create functions should throw an exception in case of invalid inputs
createOrNull functions should return null in case of invalid inputs.

Here's the goal of API that we should provide after completing this topic:

// In kotools.types.number package

fun StrictlyPositiveInt.Companion.create(number: Number): StrictlyPositiveInt
fun StrictlyPositiveInt.Companion.create(number: Number, message: (Number) -> Any): StrictlyPositiveInt
fun StrictlyPositiveInt.Companion.createOrNull(number: Number): StrictlyPositiveInt?

fun StrictlyNegativeInt.Companion.create(number: Number): StrictlyNegativeInt
fun StrictlyNegativeInt.Companion.create(number: Number, message: (Number) -> Any): StrictlyNegativeInt
fun StrictlyNegativeInt.Companion.createOrNull(number: Number): StrictlyNegativeInt?

fun PositiveInt.Companion.create(number: Number): PositiveInt
fun PositiveInt.Companion.create(number: Number, message: (Number) -> Any): PositiveInt
fun PositiveInt.Companion.createOrNull(number: Number): PositiveInt?

fun NegativeInt.Companion.create(number: Number): NegativeInt
fun NegativeInt.Companion.create(number: Number, message: (Number) -> Any): NegativeInt
fun NegativeInt.Companion.createOrNull(number: Number): NegativeInt?

fun NonZeroInt.Companion.create(number: Number): NonZeroInt
fun NonZeroInt.Companion.create(number: Number, message: (Number) -> Any): NonZeroInt
fun NonZeroInt.Companion.createOrNull(number: Number): NonZeroInt?

// In kotools.types.text package

fun NotBlankString.Companion.create(value: Any): NotBlankString
fun NotBlankString.Companion.create(value: Any, message: (Any) -> Any): NotBlankString
fun NotBlankString.Companion.createOrNull(value: Any): NotBlankString?

// In kotools.types.collection package

fun <E> NotEmptyList.Companion.create(collection: Collection<E>): NotEmptyList<E>
fun <E> NotEmptyList.Companion.create(collection: Collection<E>, message: (Collection<E>) -> Any): NotEmptyList<E>
fun <E> NotEmptyList.Companion.createOrNull(collection: Collection<E>): NotEmptyList<E>?
fun <E> NotEmptyList.Companion.of(head: E, vararg tail: E): NotEmptyList<E>

fun <E> NotEmptySet.Companion.create(collection: Collection<E>): NotEmptySet<E>
fun <E> NotEmptySet.Companion.create(collection: Collection<E>, message: (Collection<E>) -> Any): NotEmptySet<E>
fun <E> NotEmptySet.Companion.createOrNull(collection: Collection<E>): NotEmptySet<E>?
fun <E> NotEmptySet.Companion.of(head: E, vararg tail: E): NotEmptySet<E>

fun <K, V> NotEmptyMap.Companion.create(map: Map<K, V>): NotEmptyMap<K, V>
fun <K, V> NotEmptyMap.Companion.create(map: Map<K, V>, message: (Map<K, V>) -> Any): NotEmptyMap<K, V>
fun <K, V> NotEmptyMap.Companion.createOrNull(map: Map<K, V>): NotEmptyMap<K, V>?
fun <K, V> NotEmptyMap.Companion.of(head: Pair<K, V>, tail: Pair<K, V>): NotEmptyMap<K, V>

✅ Checklist

Wait for the completion of the issues below.
Close this topic as completed and update tracking issues if present.

For the StrictlyPositiveInt type:

For the StrictlyNegativeInt type:

For the PositiveInt type:

For the NegativeInt type:

For the NonZeroInt type:

For the NotBlankString type:

For the NotEmptyList type:

For the NotEmptySet type:

For the NotEmptyMap type:

The text was updated successfully, but these errors were encountered:

LVMVRQUXL · 2024-03-21T00:19:42Z

Like pointed out by the Kotlin community on Reddit, it may be useful to define an overload of the create functions accepting a custom message for the exception thrown in case of invalid input.

Here's an example for the PositiveInt type:

fun PositiveInt.Companion.create(number: Number, message: (Number) -> Any): PositiveInt

Here's an example of calling this function from Kotlin code:

val number: PositiveInt = PositiveInt.create(1) {
    "$it should be greater than or equal to zero."
}
println(number) // 1

Here's the same example of calling this function, but from Java code:

final PositiveInt result = PositiveInt.Companion.create(
    1,
    number -> number + " should be greater than or equal to zero."
);
System.out.println(result); // 1

If the specified message has a blank string representation, then it is ignored.

PositiveInt.create(-1) { "   " } // throws an IllegalArgumentException with a generic message

This idea not being essential for now, we should write it in a new discussion instead.

LVMVRQUXL · 2024-03-25T23:36:42Z

Like suggested by @lbunschoten in #335 (comment), we could mark these functions with the JvmStatic annotation for improving user experience on Java. See the Kotlin documentation on that topic.

LVMVRQUXL added feature New feature or request. common Item related to all platforms. topic A topic that we are working on. labels Mar 17, 2024

LVMVRQUXL self-assigned this Mar 17, 2024

This was referenced Mar 19, 2024

💡 Concatenations of NotBlankString #591

Closed

💥 Signature changes of NotBlankString.Companion.create* functions #541

Closed

LVMVRQUXL removed their assignment Mar 25, 2024

LVMVRQUXL modified the milestone: 4.6.0 Mar 25, 2024

LVMVRQUXL mentioned this issue Mar 26, 2024

Deprecation of factory functions using Result #263

Closed

12 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

💡 The `create` and `createOrNull` factory functions #587

💡 The `create` and `createOrNull` factory functions #587

LVMVRQUXL commented Mar 17, 2024 •

edited

LVMVRQUXL commented Mar 21, 2024 •

edited

LVMVRQUXL commented Mar 25, 2024

💡 The create and createOrNull factory functions #587

💡 The create and createOrNull factory functions #587

Comments

LVMVRQUXL commented Mar 17, 2024 • edited

📝 Description

✅ Checklist

LVMVRQUXL commented Mar 21, 2024 • edited

LVMVRQUXL commented Mar 25, 2024

💡 The `create` and `createOrNull` factory functions #587

💡 The `create` and `createOrNull` factory functions #587

LVMVRQUXL commented Mar 17, 2024 •

edited

LVMVRQUXL commented Mar 21, 2024 •

edited