Add ofNullable method to handle nullable inputs (#94)

Author: mrkh995

src/BigNumber.php

@@ -19,6 +19,7 @@
 use function is_float;
 use function is_int;
 use function is_nan;
+use function is_null;
 use function ltrim;
 use function preg_match;
 use function str_contains;
@@ -98,6 +99,26 @@ final public static function of(BigNumber|int|float|string $value): static
         return static::from($value);
     }
 
+    /**
+     * Creates a BigNumber of the given value, or returns null if the input is null.
+     *
+     * Behaves like of() for non-null values.
+     *
+     * @see BigNumber::of()
+     *
+     * @throws NumberFormatException      If the format of the number is not valid.
+     * @throws DivisionByZeroException    If the value represents a rational number with a denominator of zero.
+     * @throws RoundingNecessaryException If the value cannot be converted to an instance of the subclass without rounding.
+     */
+    public static function ofNullable(BigNumber|int|float|string|null $value): ?static
+    {
+        if (is_null($value)) {
+            return null;
+        }
+
+        return static::of($value);
+    }
+
     /**
      * Returns the minimum of the given values.
      *

tests/BigDecimalTest.php

@@ -41,6 +41,22 @@ public function testOf(int|float|string $value, string $unscaledValue, int $scal
         self::assertBigDecimalInternalValues($unscaledValue, $scale, BigDecimal::of($value));
     }
 
+    /**
+     * @param int|float|string $value         The value to convert to a BigDecimal.
+     * @param string           $unscaledValue The expected unscaled value.
+     * @param int              $scale         The expected scale.
+     */
+    #[DataProvider('providerOf')]
+    public function testOfNullableWithValidInputBehavesLikeOf(int|float|string $value, string $unscaledValue, int $scale): void
+    {
+        self::assertBigDecimalInternalValues($unscaledValue, $scale, BigDecimal::ofNullable($value));
+    }
+
+    public function testOfNullableWithNullInput(): void
+    {
+        self::assertNull(BigDecimal::ofNullable(null));
+    }
+
     public static function providerOf(): array
     {
         return [

tests/BigIntegerTest.php

@@ -50,6 +50,21 @@ public function testOf(int|float|string $value, string $expected): void
         self::assertBigIntegerEquals($expected, BigInteger::of($value));
     }
 
+    /**
+     * @param int|float|string $value    The value to convert to a BigInteger.
+     * @param string           $expected The expected string value of the result.
+     */
+    #[DataProvider('providerOf')]
+    public function testOfNullableWithValidInputBehavesLikeOf(mixed $value, string $expected): void
+    {
+        self::assertBigIntegerEquals($expected, BigInteger::ofNullable($value));
+    }
+
+    public function testOfNullableWithNullInput(): void
+    {
+        self::assertNull(BigInteger::ofNullable(null));
+    }
+
     public static function providerOf(): array
     {
         return [

tests/BigRationalTest.php

@@ -71,6 +71,23 @@ public function testOf(string $numerator, string $denominator, string $string):
         self::assertBigRationalInternalValues($numerator, $denominator, $rational);
     }
 
+    /**
+     * @param string $numerator   The expected numerator.
+     * @param string $denominator The expected denominator.
+     * @param string $string      The string to parse.
+     */
+    #[DataProvider('providerOf')]
+    public function testOfNullableWithValidInputBehavesLikeOf(string $numerator, string $denominator, string $string): void
+    {
+        $rational = BigRational::ofNullable($string);
+        self::assertBigRationalInternalValues($numerator, $denominator, $rational);
+    }
+
+    public function testOfNullableWithNullInput(): void
+    {
+        self::assertNull(BigRational::ofNullable(null));
+    }
+
     public static function providerOf(): array
     {
         return [