New type converters suffixed by OrNull and OrThrow for NotEmptyMap

[LVMVRQUXL]

Description

Like discussed in #104, we would like to introduce experimental builders for the NotEmptyMap 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 NotEmptyMap.kt file after the toNotEmptyMap function.
Their tests should be declared in the NotEmptyMapTest class after the map_toNotEmptyMap_should_fail_with_an_empty_Map 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 NotEmptyMap.kt file.

Function signatures

/**
 * Returns a [NotEmptyMap] containing all the entries of this map, or returns
 * `null` if this map is [empty][Map.isEmpty].
 *
 * Here's some usage examples:
 *
 * ```kotlin
 * var map: Map<Char, Int> = mapOf('a' to 1, 'b' to 2)
 * var result: NotEmptyMap<Char, Int>? = map.toNotEmptyMapOrNull()
 * println(result) // {a=1, b=2}
 *
 * map = emptyMap()
 * result = map.toNotEmptyMapOrNull()
 * println(result) // null
 * ```
 *
 * Please note that changes made to the original map will not be reflected on
 * the resulting [NotEmptyMap].
 *
 * ```kotlin
 * val original: MutableMap<Char, Int> = mutableMapOf('a' to 1, 'b' to 2)
 * val notEmptyMap: NotEmptyMap<Char, Int>? = original.toNotEmptyMapOrNull()
 * println(original) // {a=1, b=2}
 * println(notEmptyMap) // {a=1, b=2}
 *
 * original.clear()
 * println(original) // {}
 * println(notEmptyMap) // {a=1, b=2}
 * ```
 *
 * You can use the [toNotEmptyMapOrThrow] function for throwing an
 * [IllegalArgumentException] instead of returning `null` when this map is
 * [empty][Map.isEmpty].
 */
@ExperimentalCollectionApi
@ExperimentalSinceKotoolsTypes("4.3.1")
public fun <K, V> Map<K, V>.toNotEmptyMapOrNull(): NotEmptyMap<K, V>? {
    TODO()
}

/**
 * Returns a [NotEmptyMap] containing all the entries of this map, or throws an
 * [IllegalArgumentException] if this map is [empty][Map.isEmpty].
 *
 * Here's some usage examples:
 *
 * ```kotlin
 * var map: Map<Char, Int> = mapOf('a' to 1, 'b' to 2)
 * var result: NotEmptyMap<Char, Int> = map.toNotEmptyMapOrThrow()
 * println(result) // {a=1, b=2}
 *
 * map = emptyMap()
 * map.toNotEmptyMapOrThrow() // IllegalArgumentException
 * ```
 *
 * Please note that changes made to the original map will not be reflected on
 * the resulting [NotEmptyMap].
 *
 * ```kotlin
 * val original: MutableMap<Char, Int> = mutableMapOf('a' to 1, 'b' to 2)
 * val notEmptyMap: NotEmptyMap<Char, Int> = original.toNotEmptyMapOrThrow()
 * println(original) // {a=1, b=2}
 * println(notEmptyMap) // {a=1, b=2}
 *
 * original.clear()
 * println(original) // {}
 * println(notEmptyMap) // {a=1, b=2}
 * ```
 *
 * You can use the [toNotEmptyMapOrNull] function for returning `null` instead
 * of throwing an [IllegalArgumentException] when this map is
 * [empty][Map.isEmpty].
 */
@ExperimentalCollectionApi
@ExperimentalSinceKotoolsTypes("4.3.1")
public fun <K, V> Map<K, V>.toNotEmptyMapOrThrow(): NotEmptyMap<K, V> {
    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:
- `NotEmptyMap` (issue [#179] implemented by [@YourGitHubProfile](#)).

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

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

Commit message

feat(#179): add experimental builders for 'NotEmptyMap'

New builders: 'toNotEmptyMapOrNull' and 'toNotEmptyMapOrThrow'.
These are not implemented yet.

• Implement the toNotEmptyMapOrThrow 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(#179): implement the 'toNotEmptyMapOrThrow' function

• Implement the toNotEmptyMapOrNull 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(#179): implement the 'toNotEmptyMapOrNull' 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.