Add clamp function to BigDecimal and BigInteger

src/BigDecimal.php

@@ -297,6 +297,28 @@ public function exactlyDividedBy(BigNumber|int|float|string $that) : BigDecimal
         return $this->dividedBy($that, $scale)->stripTrailingZeros();
     }
 
+    /**
+     * Limits (clamps) this number between the given minimum and maximum values.
+     *
+     * If the number is lower than $min, returns a copy of $min.
+     * If the number is greater than $max, returns a copy of $max.
+     * Otherwise, returns this number unchanged.
+     *
+     * @param BigNumber|int|float|string $min The minimum. Must be convertible to a BigDecimal.
+     * @param BigNumber|int|float|string $max The maximum. Must be convertible to a BigDecimal.
+     *
+     * @throws MathException If min/max are not convertible to a BigDecimal.
+     */
+    public function clamp(BigNumber|int|float|string $min, BigNumber|int|float|string $max) : BigDecimal
+    {
+        if ($this->isLessThan($min)) {
+            return BigDecimal::of($min);
+        } elseif ($this->isGreaterThan($max)) {
+            return BigDecimal::of($max);
+        }
+        return $this;
+    }
+
     /**
      * Returns this number exponentiated to the given value.
      *

src/BigInteger.php

@@ -450,6 +450,29 @@ public function dividedBy(BigNumber|int|float|string $that, RoundingMode $roundi
         return new BigInteger($result);
     }
 
+    /**
+     * Limits (clamps) this number between the given minimum and maximum values.
+     *
+     * If the number is lower than $min, returns a copy of $min.
+     * If the number is greater than $max, returns a copy of $max.
+     * Otherwise, returns this number unchanged.
+     *
+     * @param BigNumber|int|float|string $min The minimum. Must be convertible to a BigInteger.
+     * @param BigNumber|int|float|string $max The maximum. Must be convertible to a BigInteger.
+     *
+     * @throws MathException If min/max are not convertible to a BigInteger.
+     */
+    public function clamp(BigNumber|int|float|string $min, BigNumber|int|float|string $max) : BigInteger
+    {
+        if ($this->isLessThan($min)) {
+            return BigInteger::of($min);
+        } elseif ($this->isGreaterThan($max)) {
+            return BigInteger::of($max);
+        }
+        return $this;
+    }
+
+
     /**
      * Returns this number exponentiated to the given value.
      *

tests/BigDecimalTest.php

@@ -1748,6 +1748,28 @@ public function testSqrtWithNegativeScale() : void
         $number->sqrt(-1);
     }
 
+    #[DataProvider('providerClamp')]
+    public function testClamp(string $number, string $min, string $max, string $expected)
+    {
+        self::assertBigDecimalEquals($expected, BigDecimal::of($number)->clamp($min, $max));
+    }
+
+    public static function providerClamp() : array
+    {
+        return [
+            ["1.00", "0.50", "1.50", "1.00"],
+            ["0.25", "0.50", "1.50", "0.50"],
+            ["2.00", "0.50", "1.50", "1.50"],
+            ["0.50", "0.50", "1.50", "0.50"],
+            ["1.50", "0.50", "1.50", "1.50"],
+            ["0.00", "0.50", "1.50", "0.50"],
+            ["1.00", "0.50", "1.50", "1.00"],
+            ["0.25", "0.00", "0.50", "0.25"],
+            ["-1.00", "0.50", "1.50", "0.50"],
+            ["-1.00", "-1.50", "-0.50", "-1.00"],
+        ];
+    }
+
     /**
      * @param string  $number        The base number.
      * @param int     $exponent      The exponent to apply.

tests/BigIntegerTest.php

@@ -1456,6 +1456,28 @@ public function testModPowZeroThrowsException() : void
         BigInteger::of(1)->modPow(1, 0);
     }
 
+    #[DataProvider('providerClamp')]
+    public function testClamp(string $number, string $min, string $max, string $expected)
+    {
+        self::assertBigIntegerEquals($expected, BigInteger::of($number)->clamp($min, $max));
+    }
+
+    public static function providerClamp() : array
+    {
+        return [
+            ["100", "50", "150", "100"],
+            ["25", "50", "150", "50"],
+            ["200", "50", "150", "150"],
+            ["50", "50", "150", "50"],
+            ["150", "50", "150", "150"],
+            ["0", "50", "150", "50"],
+            ["100", "50", "150", "100"],
+            ["25", "0", "50", "25"],
+            ["-100", "50", "150", "50"],
+            ["-100", "-150", "-50", "-100"]
+        ];
+    }
+
     /**
      * @param string $number   The base number.
      * @param int    $exponent The exponent to apply.