New type converters suffixed by OrNull and OrThrow for PositiveInt

[LVMVRQUXL]

Description

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

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 PositiveInt.kt file.

Function signatures

/**
 * Returns this number as a [PositiveInt], which may involve rounding or
 * truncation, or returns `null` if this number is
 * [strictly negative][StrictlyNegativeInt].
 *
 * Here's some usage examples:
 *
 * ```kotlin
 * var result: PositiveInt? = 1.toPositiveIntOrNull()
 * println(result) // 1
 *
 * result = 0.toPositiveIntOrNull()
 * println(result) // 0
 *
 * result = (-1).toPositiveIntOrNull()
 * println(result) // null
 * ```
 *
 * You can use the [toPositiveIntOrThrow] function for throwing an
 * [IllegalArgumentException] instead of returning `null` when this number is
 * [strictly negative][StrictlyNegativeInt].
 */
@ExperimentalNumberApi
@ExperimentalSinceKotoolsTypes("4.3.1")
public fun Number.toPositiveIntOrNull(): PositiveInt? {
    TODO()
}

/**
 * Returns this number as a [PositiveInt], which may involve rounding or
 * truncation, or throws [IllegalArgumentException] if this number is
 * [strictly negative][StrictlyNegativeInt].
 *
 * Here's some usage examples:
 *
 * ```kotlin
 * var result: PositiveInt = 1.toPositiveIntOrThrow()
 * println(result) // 1
 *
 * result = 0.toPositiveIntOrThrow()
 * println(result) // 0
 *
 * (-1).toPositiveIntOrThrow() // IllegalArgumentException
 * ```
 *
 * You can use the [toPositiveIntOrNull] function for returning `null` instead
 * of throwing an [IllegalArgumentException] when this number is
 * [strictly negative][StrictlyNegativeInt].
 */
@ExperimentalNumberApi
@ExperimentalSinceKotoolsTypes("4.3.1")
public fun Number.toPositiveIntOrThrow(): PositiveInt {
    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:
- `PositiveInt` (issue [#155] implemented by [@YourGitHubProfile](#)).

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

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

Commit message

feat(#155): add experimental builders for 'PositiveInt'

New builders: 'toPositiveIntOrNull' and 'toPositiveIntOrThrow'.
These are not implemented yet.

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

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