From e56491314a2062d10f4c2486da7a092fb45d75b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Lamarque?= <loiclamarque777@gmail.com>
Date: Thu, 9 Jan 2025 15:52:38 +0100
Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Add=20`Zero.Companion.orNull(Float)?=
 =?UTF-8?q?`=20method=20(#719)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 subprojects/library/src/api/types.api         |  1 +
 .../kotlin/org/kotools/types/Zero.kt          | 30 +++++++++++++++++++
 .../types/ZeroCompanionCommonSample.kt        |  6 ++++
 .../org/kotools/types/ZeroCompanionTest.kt    |  7 +++++
 4 files changed, 44 insertions(+)

diff --git a/subprojects/library/src/api/types.api b/subprojects/library/src/api/types.api
index e6f496da6..0b705b1f8 100644
--- a/subprojects/library/src/api/types.api
+++ b/subprojects/library/src/api/types.api
@@ -456,6 +456,7 @@ public final class org/kotools/types/Zero {
 
 public final class org/kotools/types/Zero$Companion {
 	public final synthetic fun orNull (B)Lorg/kotools/types/Zero;
+	public final synthetic fun orNull (F)Lorg/kotools/types/Zero;
 	public final synthetic fun orNull (I)Lorg/kotools/types/Zero;
 	public final synthetic fun orNull (J)Lorg/kotools/types/Zero;
 	public final synthetic fun orNull (S)Lorg/kotools/types/Zero;
diff --git a/subprojects/library/src/commonMain/kotlin/org/kotools/types/Zero.kt b/subprojects/library/src/commonMain/kotlin/org/kotools/types/Zero.kt
index 03071b181..209a53de1 100644
--- a/subprojects/library/src/commonMain/kotlin/org/kotools/types/Zero.kt
+++ b/subprojects/library/src/commonMain/kotlin/org/kotools/types/Zero.kt
@@ -645,6 +645,36 @@ public class Zero {
             null
         }
 
+        /**
+         * Creates an instance of [Zero] from the specified [number], or returns
+         * `null` if the [number] is other than zero.
+         *
+         * <br>
+         * <details>
+         * <summary>
+         *     <b>Calling from Kotlin</b>
+         * </summary>
+         *
+         * Here's an example of calling this method from Kotlin code:
+         *
+         * SAMPLE: [org.kotools.types.ZeroCompanionCommonSample.orNullWithFloat]
+         * </details>
+         * <br>
+         *
+         * This method is not available from Java code due to its non-explicit
+         * [support for nullable types](https://kotlinlang.org/docs/java-to-kotlin-nullability-guide.html#support-for-nullable-types).
+         *
+         * See the [orThrow] method for throwing an exception instead of
+         * returning `null` in case of invalid [number].
+         */
+        @ExperimentalSince(KotoolsTypesVersion.V5_0_0)
+        @JvmSynthetic
+        public fun orNull(number: Float): Zero? = try {
+            this.orThrow(number)
+        } catch (exception: IllegalArgumentException) {
+            null
+        }
+
         /**
          * Creates an instance of [Zero] from the specified [number], or throws
          * an [IllegalArgumentException] if the [number] is other than zero.
diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt
index 306e7b941..69bbfcf4e 100644
--- a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt
+++ b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionCommonSample.kt
@@ -32,6 +32,12 @@ class ZeroCompanionCommonSample {
         assertNotNull(zero)
     }
 
+    @Test
+    fun orNullWithFloat() {
+        val zero: Zero? = Zero.orNull(0f)
+        assertNotNull(zero)
+    }
+
     @Test
     fun orThrowWithByte() {
         val number: Byte = 0
diff --git a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt
index 869ac2074..564b16661 100644
--- a/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt
+++ b/subprojects/library/src/commonTest/kotlin/org/kotools/types/ZeroCompanionTest.kt
@@ -47,6 +47,13 @@ class ZeroCompanionTest {
         assertNull(actual)
     }
 
+    @Test
+    fun orNullShouldFailWithFloatOtherThanZero() {
+        val number: Float = Float.randomNonZero()
+        val actual: Zero? = Zero.orNull(number)
+        assertNull(actual)
+    }
+
     @Test
     fun orThrowShouldFailWithByteOtherThanZero() {
         val number: Byte = setOf(Byte.MIN_VALUE..-1, 1..Byte.MAX_VALUE)