Add ofNullable method to handle nullable inputs

src/BigNumber.php

@@ -71,6 +71,34 @@ 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.
+     *
+     * 
+     * The concrete return type is dependent on the given value, with the following rules:
+     *
+     * - BigNumber instances are returned as is
+     * - null values are returned as is
+     * - integer numbers are returned as BigInteger
+     * - floating point numbers are converted to a string then parsed as such\
+     * - strings containing a `/` character are returned as BigRational
+     * - strings containing a `.` character or using an exponential notation are returned as BigDecimal
+     * - strings containing only digits with an optional leading `+` or `-` sign are returned as BigInteger
+     *
+     * @param BigNumber|int|float|string|null $value The value to convert.
+     *
+     * @return static|null A BigNumber instance (of the called class type), or null if the input was null.
+     * 
+     * @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);
+    }
 
     /**
      * @throws NumberFormatException If the format of the number is not valid.

tests/BigDecimalTest.php

@@ -29,6 +29,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::of($value));
+    }
+
+    public function testOfNullableWithNullInput(): void
+    {
+        $this->assertNull(BigDecimal::ofNullable(null));
+    }
+
     public static function providerOf() : array
     {
         return [

tests/BigIntegerTest.php

@@ -31,6 +31,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
+    {
+        $this->assertNull(BigInteger::ofNullable(null));
+    }
+
     public static function providerOf() : array
     {
         return [

tests/BigRationalTest.php

@@ -61,6 +61,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
+    {
+        $this->assertNull(BigRational::ofNullable(null));
+    }
+
     public static function providerOf() : array
     {
         return [