New type converters suffixed by OrNull and OrThrow for NotEmptyList

[LVMVRQUXL]

Description

Like discussed in #104, we would like to introduce experimental builders for the NotEmptyList type that should:

• return null in case of a failure if the builder is suffixed by OrNull
• throw an IllegalArgumentException in case of a failure if the builder is suffixed by OrThrow.

These builders should work on all platforms and should be declared in the NotEmptyList.kt file after the toNotEmptyList function.
Their tests should be declared in the NotEmptyListTest class after the collection_toNotEmptyList_should_fail_with_an_empty_Collection function.

Dependencies

This issue is blocked by the following ones:

• New ExperimentalCollectionApi annotation #177

Checklist

• Follow the Issue implementation section in the contributing guidelines until the Checking the API binaries section.
• Copy the Kotlin code below and paste it in the NotEmptyList.kt file.

Function signatures

/**
 * Returns a [NotEmptyList] containing all the elements of this collection, or
 * returns `null` if this collection is [empty][Collection.isEmpty].
 *
 * Here's some usage examples:
 *
 * ```kotlin
 * var collection: Collection<Int> = listOf(1, 2, 3)
 * var result: NotEmptyList<Int>? = collection.toNotEmptyListOrNull()
 * println(result) // [1, 2, 3]
 *
 * collection = emptyList()
 * result = collection.toNotEmptyListOrNull()
 * println(result) // null
 * ```
 *
 * Please note that changes made to the original collection will not be
 * reflected on the resulting [NotEmptyList].
 *
 * ```kotlin
 * val original: MutableCollection<Int> = mutableListOf(1, 2, 3)
 * val notEmptyList: NotEmptyList<Int>? = original.toNotEmptyListOrNull()
 * println(original) // [1, 2, 3]
 * println(notEmptyList) // [1, 2, 3]
 *
 * original.clear()
 * println(original) // []
 * println(notEmptyList) // [1, 2, 3]
 * ```
 *
 * You can use the [toNotEmptyListOrThrow] function for throwing an
 * [IllegalArgumentException] instead of returning `null` when this collection
 * is [empty][Collection.isEmpty].
 */
@ExperimentalCollectionApi
@ExperimentalSinceKotoolsTypes("4.3.1")
public fun <E> Collection<E>.toNotEmptyListOrNull(): NotEmptyList<E>? {
    TODO()
}

/**
 * Returns a [NotEmptyList] containing all the elements of this collection, or
 * throws an [IllegalArgumentException] if this collection is
 * [empty][Collection.isEmpty].
 *
 * Here's some usage examples:
 *
 * ```kotlin
 * var collection: Collection<Int> = listOf(1, 2, 3)
 * var result: NotEmptyList<Int> = collection.toNotEmptyListOrThrow()
 * println(result) // [1, 2, 3]
 *
 * collection = emptyList()
 * collection.toNotEmptyListOrThrow() // IllegalArgumentException
 * ```
 *
 * Please note that changes made to the original collection will not be
 * reflected on the resulting [NotEmptyList].
 *
 * ```kotlin
 * val original: MutableCollection<Int> = mutableListOf(1, 2, 3)
 * val notEmptyList: NotEmptyList<Int> = original.toNotEmptyListOrThrow()
 * println(original) // [1, 2, 3]
 * println(notEmptyList) // [1, 2, 3]
 *
 * original.clear()
 * println(original) // []
 * println(notEmptyList) // [1, 2, 3]
 * ```
 *
 * You can use the [toNotEmptyListOrNull] function for returning `null` instead
 * of throwing an [IllegalArgumentException] when this collection is
 * [empty][Collection.isEmpty].
 */
@ExperimentalCollectionApi
@ExperimentalSinceKotoolsTypes("4.3.1")
public fun <E> Collection<E>.toNotEmptyListOrThrow(): NotEmptyList<E> {
    TODO()
}

• Check your changes in the generated documentation.
• Check your changes in the public API binaries and update them.
• Copy the following Markdown code block and paste it in the Unreleased section in the CHANGELOG, replacing the YourGitHubProfile placeholder by your GitHub profile (see an example here).

Entry in changelog

### Added

**Experimental** builders suffixed by `OrNull` and `OrThrow` for the following
types:
- `NotEmptyList` (issue [#176] implemented by [@YourGitHubProfile](#)).

[#176]: https://github.com/kotools/types/issues/176

• Commit your local changes by running the git commit -a command in your terminal with the message below.

Commit message

feat(#176): add experimental builders for 'NotEmptyList'

New builders: 'toNotEmptyListOrNull' and 'toNotEmptyListOrThrow'.
These are not implemented yet.

• Implement the toNotEmptyListOrThrow function by resolving the following tasks:
  • Add unit tests for this new function.
  • Run tests on the JVM platform. These should fail at this stage.
  • Implement this new function without changing its signature.
  • Run tests on the JVM platform. These should pass at this stage.
  • Commit your local changes by running the git commit -a command in your terminal with the message below.

Commit message

feat(#176): implement the 'toNotEmptyListOrThrow' function

• Implement the toNotEmptyListOrNull function by resolving the following tasks:
  • Add unit tests for this new function.
  • Run tests on the JVM platform. These should fail at this stage.
  • Implement this new function without changing its signature.
  • Run tests on the JVM platform. These should pass at this stage.
  • Commit your local changes by running the git commit -a command in your terminal with the message below.

Commit message

feat(#176): implement the 'toNotEmptyListOrNull' function

• Create a Pull Request.

Maintainers only

• Refactor the construction of the type by using functional programming tools provided by Kotlin for improving its readability, composability and performance.

[LVMVRQUXL]

Done.