First Commit

vendor/brick/math/src/Internal/Calculator.php

@@ -0,0 +1,757 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal;
+
+use Brick\Math\RoundingMode;
+
+use function chr;
+use function intdiv;
+use function ltrim;
+use function ord;
+use function str_repeat;
+use function strlen;
+use function strpos;
+use function strrev;
+use function strtolower;
+use function substr;
+
+/**
+ * Performs basic operations on arbitrary size integers.
+ *
+ * Unless otherwise specified, all parameters must be validated as non-empty strings of digits,
+ * without leading zero, and with an optional leading minus sign if the number is not zero.
+ *
+ * Any other parameter format will lead to undefined behaviour.
+ * All methods must return strings respecting this format, unless specified otherwise.
+ *
+ * @internal
+ */
+abstract readonly class Calculator
+{
+    /**
+     * The alphabet for converting from and to base 2 to 36, lowercase.
+     */
+    public const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+
+    /**
+     * Returns the absolute value of a number.
+     *
+     * @pure
+     */
+    final public function abs(string $n): string
+    {
+        return ($n[0] === '-') ? substr($n, 1) : $n;
+    }
+
+    /**
+     * Negates a number.
+     *
+     * @pure
+     */
+    final public function neg(string $n): string
+    {
+        if ($n === '0') {
+            return '0';
+        }
+
+        if ($n[0] === '-') {
+            return substr($n, 1);
+        }
+
+        return '-' . $n;
+    }
+
+    /**
+     * Compares two numbers.
+     *
+     * Returns -1 if the first number is less than, 0 if equal to, 1 if greater than the second number.
+     *
+     * @return -1|0|1
+     *
+     * @pure
+     */
+    final public function cmp(string $a, string $b): int
+    {
+        [$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
+
+        if ($aNeg && ! $bNeg) {
+            return -1;
+        }
+
+        if ($bNeg && ! $aNeg) {
+            return 1;
+        }
+
+        $aLen = strlen($aDig);
+        $bLen = strlen($bDig);
+
+        if ($aLen < $bLen) {
+            $result = -1;
+        } elseif ($aLen > $bLen) {
+            $result = 1;
+        } else {
+            $result = $aDig <=> $bDig;
+        }
+
+        return $aNeg ? -$result : $result;
+    }
+
+    /**
+     * Adds two numbers.
+     *
+     * @pure
+     */
+    abstract public function add(string $a, string $b): string;
+
+    /**
+     * Subtracts two numbers.
+     *
+     * @pure
+     */
+    abstract public function sub(string $a, string $b): string;
+
+    /**
+     * Multiplies two numbers.
+     *
+     * @pure
+     */
+    abstract public function mul(string $a, string $b): string;
+
+    /**
+     * Returns the quotient of the division of two numbers.
+     *
+     * @param string $a The dividend.
+     * @param string $b The divisor, must not be zero.
+     *
+     * @return string The quotient.
+     *
+     * @pure
+     */
+    abstract public function divQ(string $a, string $b): string;
+
+    /**
+     * Returns the remainder of the division of two numbers.
+     *
+     * @param string $a The dividend.
+     * @param string $b The divisor, must not be zero.
+     *
+     * @return string The remainder.
+     *
+     * @pure
+     */
+    abstract public function divR(string $a, string $b): string;
+
+    /**
+     * Returns the quotient and remainder of the division of two numbers.
+     *
+     * @param string $a The dividend.
+     * @param string $b The divisor, must not be zero.
+     *
+     * @return array{string, string} An array containing the quotient and remainder.
+     *
+     * @pure
+     */
+    abstract public function divQR(string $a, string $b): array;
+
+    /**
+     * Exponentiates a number.
+     *
+     * @param string $a The base number.
+     * @param int    $e The exponent, validated as a non-negative integer.
+     *
+     * @return string The power.
+     *
+     * @pure
+     */
+    abstract public function pow(string $a, int $e): string;
+
+    /**
+     * @param string $b The modulus; must not be zero.
+     *
+     * @pure
+     */
+    public function mod(string $a, string $b): string
+    {
+        return $this->divR($this->add($this->divR($a, $b), $b), $b);
+    }
+
+    /**
+     * Returns the modular multiplicative inverse of $x modulo $m.
+     *
+     * If $x has no multiplicative inverse mod m, this method must return null.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library has built-in support.
+     *
+     * @param string $m The modulus; must not be negative or zero.
+     *
+     * @pure
+     */
+    public function modInverse(string $x, string $m): ?string
+    {
+        if ($m === '1') {
+            return '0';
+        }
+
+        $modVal = $x;
+
+        if ($x[0] === '-' || ($this->cmp($this->abs($x), $m) >= 0)) {
+            $modVal = $this->mod($x, $m);
+        }
+
+        [$g, $x] = $this->gcdExtended($modVal, $m);
+
+        if ($g !== '1') {
+            return null;
+        }
+
+        return $this->mod($this->add($this->mod($x, $m), $m), $m);
+    }
+
+    /**
+     * Raises a number into power with modulo.
+     *
+     * @param string $base The base number.
+     * @param string $exp  The exponent; must be positive or zero.
+     * @param string $mod  The modulus; must be strictly positive.
+     *
+     * @pure
+     */
+    abstract public function modPow(string $base, string $exp, string $mod): string;
+
+    /**
+     * Returns the greatest common divisor of the two numbers.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for GCD calculations.
+     *
+     * @return string The GCD, always positive, or zero if both arguments are zero.
+     *
+     * @pure
+     */
+    public function gcd(string $a, string $b): string
+    {
+        while ($b !== '0') {
+            [$a, $b] = [$b, $this->divR($a, $b)];
+        }
+
+        return $this->abs($a);
+    }
+
+    /**
+     * Returns the least common multiple of the two numbers.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for LCM calculations.
+     *
+     * @return string The LCM, always positive, or zero if at least one argument is zero.
+     *
+     * @pure
+     */
+    public function lcm(string $a, string $b): string
+    {
+        if ($a === '0' || $b === '0') {
+            return '0';
+        }
+
+        return $this->divQ($this->abs($this->mul($a, $b)), $this->gcd($a, $b));
+    }
+
+    /**
+     * Returns the square root of the given number, rounded down.
+     *
+     * The result is the largest x such that x² ≤ n.
+     * The input MUST NOT be negative.
+     *
+     * @pure
+     */
+    abstract public function sqrt(string $n): string;
+
+    /**
+     * Returns the integer nth root of the given number, truncated toward zero.
+     *
+     * If $n is non-negative, the result is the largest x such that x^$k ≤ $n (floor).
+     * If $n is negative, $k MUST be odd, and the result is the negation of the floor root of |$n|
+     * (i.e., truncation toward zero: the smallest x such that x^$k ≥ $n).
+     *
+     * The caller MUST guarantee that $k ≥ 1 and that $n is non-negative when $k is even.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for nth root calculations.
+     *
+     * @param string $n The number. May be negative only when $k is odd.
+     * @param int    $k The root degree. Must be strictly positive.
+     *
+     * @pure
+     */
+    public function nthRoot(string $n, int $k): string
+    {
+        if ($n === '0') {
+            return '0';
+        }
+
+        $negative = ($n[0] === '-');
+        $m = $negative ? substr($n, 1) : $n;
+
+        if ($m === '1') {
+            return $negative ? '-1' : '1';
+        }
+
+        // Initial overshoot: 10^ceil(strlen(m)/k) is strictly greater than the true root.
+        // Newton-Raphson requires starting above the true root to converge monotonically down.
+        $x = '1' . str_repeat('0', intdiv(strlen($m) - 1, $k) + 1);
+
+        $kStr = (string) $k;
+        $kMinusOneStr = (string) ($k - 1);
+
+        // Newton-Raphson recurrence for integer nth root:
+        //   x_{i+1} = floor(((k-1) * x_i + floor(m / x_i^{k-1})) / k)
+        for (; ;) {
+            $nx = $this->divQ(
+                $this->add(
+                    $this->mul($kMinusOneStr, $x),
+                    $this->divQ($m, $this->pow($x, $k - 1)),
+                ),
+                $kStr,
+            );
+
+            if ($this->cmp($nx, $x) >= 0) {
+                break;
+            }
+
+            $x = $nx;
+        }
+
+        return $negative ? $this->neg($x) : $x;
+    }
+
+    /**
+     * Converts a number from an arbitrary base.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for base conversion.
+     *
+     * @param string $number The number, positive or zero, non-empty, case-insensitively validated for the given base.
+     * @param int    $base   The base of the number, validated from 2 to 36.
+     *
+     * @return string The converted number, following the Calculator conventions.
+     *
+     * @pure
+     */
+    public function fromBase(string $number, int $base): string
+    {
+        return $this->fromArbitraryBase(strtolower($number), self::ALPHABET, $base);
+    }
+
+    /**
+     * Converts a number to an arbitrary base.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for base conversion.
+     *
+     * @param string $number The number to convert, following the Calculator conventions.
+     * @param int    $base   The base to convert to, validated from 2 to 36.
+     *
+     * @return string The converted number, lowercase.
+     *
+     * @pure
+     */
+    public function toBase(string $number, int $base): string
+    {
+        $negative = ($number[0] === '-');
+
+        if ($negative) {
+            $number = substr($number, 1);
+        }
+
+        $number = $this->toArbitraryBase($number, self::ALPHABET, $base);
+
+        if ($negative) {
+            return '-' . $number;
+        }
+
+        return $number;
+    }
+
+    /**
+     * Converts a non-negative number in an arbitrary base using a custom alphabet, to base 10.
+     *
+     * @param string $number   The number to convert, validated as a non-empty string,
+     *                         containing only chars in the given alphabet/base.
+     * @param string $alphabet The alphabet that contains every digit, validated as 2 chars minimum.
+     * @param int    $base     The base of the number, validated from 2 to alphabet length.
+     *
+     * @return string The number in base 10, following the Calculator conventions.
+     *
+     * @pure
+     */
+    final public function fromArbitraryBase(string $number, string $alphabet, int $base): string
+    {
+        // remove leading "zeros"
+        $number = ltrim($number, $alphabet[0]);
+
+        if ($number === '') {
+            return '0';
+        }
+
+        // optimize for "one"
+        if ($number === $alphabet[1]) {
+            return '1';
+        }
+
+        $result = '0';
+        $power = '1';
+
+        $base = (string) $base;
+
+        for ($i = strlen($number) - 1; $i >= 0; $i--) {
+            $index = strpos($alphabet, $number[$i]);
+
+            if ($index !== 0) {
+                $result = $this->add(
+                    $result,
+                    ($index === 1) ? $power : $this->mul($power, (string) $index),
+                );
+            }
+
+            if ($i !== 0) {
+                $power = $this->mul($power, $base);
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Converts a non-negative number to an arbitrary base using a custom alphabet.
+     *
+     * @param string $number   The number to convert, positive or zero, following the Calculator conventions.
+     * @param string $alphabet The alphabet that contains every digit, validated as 2 chars minimum.
+     * @param int    $base     The base to convert to, validated from 2 to alphabet length.
+     *
+     * @return string The converted number in the given alphabet.
+     *
+     * @pure
+     */
+    final public function toArbitraryBase(string $number, string $alphabet, int $base): string
+    {
+        if ($number === '0') {
+            return $alphabet[0];
+        }
+
+        $base = (string) $base;
+        $result = '';
+
+        while ($number !== '0') {
+            [$number, $remainder] = $this->divQR($number, $base);
+            $remainder = (int) $remainder;
+
+            $result .= $alphabet[$remainder];
+        }
+
+        return strrev($result);
+    }
+
+    /**
+     * Performs a rounded division.
+     *
+     * When the remainder of the division is not zero, rounding is performed according to the rounding mode provided,
+     * unless RoundingMode::Unnecessary is used, in which case the method returns null.
+     *
+     * @param string       $a            The dividend.
+     * @param string       $b            The divisor, must not be zero.
+     * @param RoundingMode $roundingMode The rounding mode.
+     *
+     * @pure
+     */
+    final public function divRound(string $a, string $b, RoundingMode $roundingMode): ?string
+    {
+        [$quotient, $remainder] = $this->divQR($a, $b);
+
+        $hasDiscardedFraction = ($remainder !== '0');
+        $isPositiveOrZero = ($a[0] === '-') === ($b[0] === '-');
+
+        $discardedFractionSign = function () use ($remainder, $b): int {
+            $r = $this->abs($this->mul($remainder, '2'));
+            $b = $this->abs($b);
+
+            return $this->cmp($r, $b);
+        };
+
+        $increment = false;
+
+        switch ($roundingMode) {
+            case RoundingMode::Unnecessary:
+                if ($hasDiscardedFraction) {
+                    return null;
+                }
+
+                break;
+
+            case RoundingMode::Up:
+                $increment = $hasDiscardedFraction;
+
+                break;
+
+            case RoundingMode::Down:
+                break;
+
+            case RoundingMode::Ceiling:
+                $increment = $hasDiscardedFraction && $isPositiveOrZero;
+
+                break;
+
+            case RoundingMode::Floor:
+                $increment = $hasDiscardedFraction && ! $isPositiveOrZero;
+
+                break;
+
+            case RoundingMode::HalfUp:
+                $increment = $discardedFractionSign() >= 0;
+
+                break;
+
+            case RoundingMode::HalfDown:
+                $increment = $discardedFractionSign() > 0;
+
+                break;
+
+            case RoundingMode::HalfCeiling:
+                $increment = $isPositiveOrZero ? $discardedFractionSign() >= 0 : $discardedFractionSign() > 0;
+
+                break;
+
+            case RoundingMode::HalfFloor:
+                $increment = $isPositiveOrZero ? $discardedFractionSign() > 0 : $discardedFractionSign() >= 0;
+
+                break;
+
+            case RoundingMode::HalfEven:
+                $lastDigit = (int) $quotient[-1];
+                $lastDigitIsEven = ($lastDigit % 2 === 0);
+                $increment = $lastDigitIsEven ? $discardedFractionSign() > 0 : $discardedFractionSign() >= 0;
+
+                break;
+        }
+
+        if ($increment) {
+            return $this->add($quotient, $isPositiveOrZero ? '1' : '-1');
+        }
+
+        return $quotient;
+    }
+
+    /**
+     * Calculates bitwise AND of two numbers.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for bitwise operations.
+     *
+     * @pure
+     */
+    public function and(string $a, string $b): string
+    {
+        return $this->bitwise('and', $a, $b);
+    }
+
+    /**
+     * Calculates bitwise OR of two numbers.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for bitwise operations.
+     *
+     * @pure
+     */
+    public function or(string $a, string $b): string
+    {
+        return $this->bitwise('or', $a, $b);
+    }
+
+    /**
+     * Calculates bitwise XOR of two numbers.
+     *
+     * This method can be overridden by the concrete implementation if the underlying library
+     * has built-in support for bitwise operations.
+     *
+     * @pure
+     */
+    public function xor(string $a, string $b): string
+    {
+        return $this->bitwise('xor', $a, $b);
+    }
+
+    /**
+     * Extracts the sign & digits of the operands.
+     *
+     * @return array{bool, bool, string, string} Whether $a and $b are negative, followed by their digits.
+     *
+     * @pure
+     */
+    final protected function init(string $a, string $b): array
+    {
+        return [
+            $aNeg = ($a[0] === '-'),
+            $bNeg = ($b[0] === '-'),
+
+            $aNeg ? substr($a, 1) : $a,
+            $bNeg ? substr($b, 1) : $b,
+        ];
+    }
+
+    /**
+     * @param string $a Must be non-negative.
+     * @param string $b Must be non-negative.
+     *
+     * @return array{string, string} GCD, X
+     *
+     * @pure
+     */
+    private function gcdExtended(string $a, string $b): array
+    {
+        // Iterative extended Euclidean algorithm; recursion would exhaust memory on large inputs.
+        [$r0, $r1] = [$a, $b];
+        [$x0, $x1] = ['1', '0'];
+
+        while ($r1 !== '0') {
+            [$q, $r] = $this->divQR($r0, $r1);
+
+            [$r0, $r1] = [$r1, $r];
+            [$x0, $x1] = [$x1, $this->sub($x0, $this->mul($q, $x1))];
+        }
+
+        return [$r0, $x0];
+    }
+
+    /**
+     * Performs a bitwise operation on a decimal number.
+     *
+     * @param 'and'|'or'|'xor' $operator The operator to use.
+     * @param string           $a        The left operand.
+     * @param string           $b        The right operand.
+     *
+     * @pure
+     */
+    private function bitwise(string $operator, string $a, string $b): string
+    {
+        [$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
+
+        $aBin = $this->toBinary($aDig);
+        $bBin = $this->toBinary($bDig);
+
+        $aLen = strlen($aBin);
+        $bLen = strlen($bBin);
+
+        if ($aLen > $bLen) {
+            $bBin = str_repeat("\x00", $aLen - $bLen) . $bBin;
+        } elseif ($bLen > $aLen) {
+            $aBin = str_repeat("\x00", $bLen - $aLen) . $aBin;
+        }
+
+        if ($aNeg) {
+            $aBin = $this->twosComplement($aBin);
+        }
+        if ($bNeg) {
+            $bBin = $this->twosComplement($bBin);
+        }
+
+        $value = match ($operator) {
+            'and' => $aBin & $bBin,
+            'or' => $aBin | $bBin,
+            'xor' => $aBin ^ $bBin,
+        };
+
+        $negative = match ($operator) {
+            'and' => $aNeg and $bNeg,
+            'or' => $aNeg or $bNeg,
+            'xor' => $aNeg xor $bNeg,
+        };
+
+        if ($negative) {
+            $value = $this->twosComplement($value);
+        }
+
+        $result = $this->toDecimal($value);
+
+        return $negative ? $this->neg($result) : $result;
+    }
+
+    /**
+     * @param string $number A positive, binary number.
+     *
+     * @pure
+     */
+    private function twosComplement(string $number): string
+    {
+        $xor = str_repeat("\xff", strlen($number));
+
+        $number ^= $xor;
+
+        for ($i = strlen($number) - 1; $i >= 0; $i--) {
+            $byte = ord($number[$i]);
+
+            if (++$byte !== 256) {
+                $number[$i] = chr($byte);
+
+                break;
+            }
+
+            $number[$i] = "\x00";
+
+            if ($i === 0) {
+                $number = "\x01" . $number;
+            }
+        }
+
+        return $number;
+    }
+
+    /**
+     * Converts a decimal number to a binary string.
+     *
+     * @param string $number The number to convert, positive or zero, only digits.
+     *
+     * @pure
+     */
+    private function toBinary(string $number): string
+    {
+        $result = '';
+
+        while ($number !== '0') {
+            [$number, $remainder] = $this->divQR($number, '256');
+            $result .= chr((int) $remainder);
+        }
+
+        return strrev($result);
+    }
+
+    /**
+     * Returns the positive decimal representation of a binary number.
+     *
+     * @param string $bytes The bytes representing the number.
+     *
+     * @pure
+     */
+    private function toDecimal(string $bytes): string
+    {
+        $result = '0';
+        $power = '1';
+
+        for ($i = strlen($bytes) - 1; $i >= 0; $i--) {
+            $index = ord($bytes[$i]);
+
+            if ($index !== 0) {
+                $result = $this->add(
+                    $result,
+                    ($index === 1) ? $power : $this->mul($power, (string) $index),
+                );
+            }
+
+            if ($i !== 0) {
+                $power = $this->mul($power, '256');
+            }
+        }
+
+        return $result;
+    }
+}

vendor/brick/math/src/Internal/Calculator/BcMathCalculator.php

@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal\Calculator;
+
+use Brick\Math\Internal\Calculator;
+use Override;
+
+use function bcadd;
+use function bcdiv;
+use function bcmod;
+use function bcmul;
+use function bcpow;
+use function bcpowmod;
+use function bcsqrt;
+use function bcsub;
+
+/**
+ * Calculator implementation built around the bcmath library.
+ *
+ * @internal
+ */
+final readonly class BcMathCalculator extends Calculator
+{
+    #[Override]
+    public function add(string $a, string $b): string
+    {
+        return bcadd($a, $b, 0);
+    }
+
+    #[Override]
+    public function sub(string $a, string $b): string
+    {
+        return bcsub($a, $b, 0);
+    }
+
+    #[Override]
+    public function mul(string $a, string $b): string
+    {
+        return bcmul($a, $b, 0);
+    }
+
+    #[Override]
+    public function divQ(string $a, string $b): string
+    {
+        return bcdiv($a, $b, 0);
+    }
+
+    #[Override]
+    public function divR(string $a, string $b): string
+    {
+        return bcmod($a, $b, 0);
+    }
+
+    #[Override]
+    public function divQR(string $a, string $b): array
+    {
+        $q = bcdiv($a, $b, 0);
+        $r = bcmod($a, $b, 0);
+
+        return [$q, $r];
+    }
+
+    #[Override]
+    public function pow(string $a, int $e): string
+    {
+        if ($e === 0) {
+            return '1';
+        }
+
+        // bcpow() allocates memory proportional to the exponent even when the base is trivial,
+        // exhausting memory on 32-bit builds at large exponents.
+        if ($a === '0' || $a === '1') {
+            return $a;
+        }
+
+        if ($a === '-1') {
+            return $e % 2 === 0 ? '1' : '-1';
+        }
+
+        return bcpow($a, (string) $e, 0);
+    }
+
+    #[Override]
+    public function modPow(string $base, string $exp, string $mod): string
+    {
+        // normalize to Euclidean representative so modPow() stays consistent with mod()
+        $base = $this->mod($base, $mod);
+
+        return bcpowmod($base, $exp, $mod, 0);
+    }
+
+    #[Override]
+    public function sqrt(string $n): string
+    {
+        return bcsqrt($n, 0);
+    }
+}

vendor/brick/math/src/Internal/Calculator/GmpCalculator.php

@@ -0,0 +1,167 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal\Calculator;
+
+use Brick\Math\Internal\Calculator;
+use GMP;
+use Override;
+
+use function gmp_add;
+use function gmp_and;
+use function gmp_div_q;
+use function gmp_div_qr;
+use function gmp_div_r;
+use function gmp_gcd;
+use function gmp_init;
+use function gmp_invert;
+use function gmp_lcm;
+use function gmp_mul;
+use function gmp_or;
+use function gmp_pow;
+use function gmp_powm;
+use function gmp_root;
+use function gmp_sqrt;
+use function gmp_strval;
+use function gmp_sub;
+use function gmp_xor;
+use function substr;
+
+/**
+ * Calculator implementation built around the GMP library.
+ *
+ * @internal
+ */
+final readonly class GmpCalculator extends Calculator
+{
+    #[Override]
+    public function add(string $a, string $b): string
+    {
+        return gmp_strval(gmp_add($a, $b));
+    }
+
+    #[Override]
+    public function sub(string $a, string $b): string
+    {
+        return gmp_strval(gmp_sub($a, $b));
+    }
+
+    #[Override]
+    public function mul(string $a, string $b): string
+    {
+        return gmp_strval(gmp_mul($a, $b));
+    }
+
+    #[Override]
+    public function divQ(string $a, string $b): string
+    {
+        return gmp_strval(gmp_div_q($a, $b));
+    }
+
+    #[Override]
+    public function divR(string $a, string $b): string
+    {
+        return gmp_strval(gmp_div_r($a, $b));
+    }
+
+    #[Override]
+    public function divQR(string $a, string $b): array
+    {
+        [$q, $r] = gmp_div_qr($a, $b);
+
+        /**
+         * @var GMP $q
+         * @var GMP $r
+         */
+        return [
+            gmp_strval($q),
+            gmp_strval($r),
+        ];
+    }
+
+    #[Override]
+    public function pow(string $a, int $e): string
+    {
+        return gmp_strval(gmp_pow($a, $e));
+    }
+
+    #[Override]
+    public function modInverse(string $x, string $m): ?string
+    {
+        $result = gmp_invert($x, $m);
+
+        if ($result === false) {
+            return null;
+        }
+
+        return gmp_strval($result);
+    }
+
+    #[Override]
+    public function modPow(string $base, string $exp, string $mod): string
+    {
+        return gmp_strval(gmp_powm($base, $exp, $mod));
+    }
+
+    #[Override]
+    public function gcd(string $a, string $b): string
+    {
+        return gmp_strval(gmp_gcd($a, $b));
+    }
+
+    #[Override]
+    public function lcm(string $a, string $b): string
+    {
+        return gmp_strval(gmp_lcm($a, $b));
+    }
+
+    #[Override]
+    public function fromBase(string $number, int $base): string
+    {
+        return gmp_strval(gmp_init($number, $base));
+    }
+
+    #[Override]
+    public function toBase(string $number, int $base): string
+    {
+        return gmp_strval($number, $base);
+    }
+
+    #[Override]
+    public function and(string $a, string $b): string
+    {
+        return gmp_strval(gmp_and($a, $b));
+    }
+
+    #[Override]
+    public function or(string $a, string $b): string
+    {
+        return gmp_strval(gmp_or($a, $b));
+    }
+
+    #[Override]
+    public function xor(string $a, string $b): string
+    {
+        return gmp_strval(gmp_xor($a, $b));
+    }
+
+    #[Override]
+    public function sqrt(string $n): string
+    {
+        return gmp_strval(gmp_sqrt($n));
+    }
+
+    #[Override]
+    public function nthRoot(string $n, int $k): string
+    {
+        // Delegate on the absolute value and re-apply the sign ourselves so the
+        // truncation-toward-zero convention matches the shared Newton-Raphson fallback
+        // bit-for-bit, regardless of any PHP/GMP behaviour changes for negative inputs.
+        if ($n[0] === '-') {
+            return '-' . gmp_strval(gmp_root(substr($n, 1), $k));
+        }
+
+        return gmp_strval(gmp_root($n, $k));
+    }
+}

vendor/brick/math/src/Internal/Calculator/NativeCalculator.php

@@ -0,0 +1,616 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal\Calculator;
+
+use Brick\Math\Internal\Calculator;
+use Override;
+
+use function assert;
+use function in_array;
+use function intdiv;
+use function is_int;
+use function ltrim;
+use function str_pad;
+use function str_repeat;
+use function strcmp;
+use function strlen;
+use function substr;
+
+use const PHP_INT_SIZE;
+use const STR_PAD_LEFT;
+
+/**
+ * Calculator implementation using only native PHP code.
+ *
+ * @internal
+ */
+final readonly class NativeCalculator extends Calculator
+{
+    /**
+     * The max number of digits the platform can natively add, subtract, multiply or divide without overflow.
+     * For multiplication, this represents the max sum of the lengths of both operands.
+     *
+     * In addition, it is assumed that an extra digit can hold a carry (1) without overflowing.
+     * Example: 32-bit: max number 1,999,999,999 (9 digits + carry)
+     *          64-bit: max number 1,999,999,999,999,999,999 (18 digits + carry)
+     */
+    private int $maxDigits;
+
+    /**
+     * @pure
+     *
+     * @codeCoverageIgnore
+     */
+    public function __construct()
+    {
+        $this->maxDigits = match (PHP_INT_SIZE) {
+            4 => 9,
+            8 => 18,
+        };
+    }
+
+    #[Override]
+    public function add(string $a, string $b): string
+    {
+        /**
+         * @var numeric-string $a
+         * @var numeric-string $b
+         */
+        $result = $a + $b;
+
+        if (is_int($result)) {
+            return (string) $result;
+        }
+
+        if ($a === '0') {
+            return $b;
+        }
+
+        if ($b === '0') {
+            return $a;
+        }
+
+        [$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
+
+        $result = $aNeg === $bNeg ? $this->doAdd($aDig, $bDig) : $this->doSub($aDig, $bDig);
+
+        if ($aNeg) {
+            $result = $this->neg($result);
+        }
+
+        return $result;
+    }
+
+    #[Override]
+    public function sub(string $a, string $b): string
+    {
+        return $this->add($a, $this->neg($b));
+    }
+
+    #[Override]
+    public function mul(string $a, string $b): string
+    {
+        /**
+         * @var numeric-string $a
+         * @var numeric-string $b
+         */
+        $result = $a * $b;
+
+        if (is_int($result)) {
+            return (string) $result;
+        }
+
+        if ($a === '0' || $b === '0') {
+            return '0';
+        }
+
+        if ($a === '1') {
+            return $b;
+        }
+
+        if ($b === '1') {
+            return $a;
+        }
+
+        if ($a === '-1') {
+            return $this->neg($b);
+        }
+
+        if ($b === '-1') {
+            return $this->neg($a);
+        }
+
+        [$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
+
+        $result = $this->doMul($aDig, $bDig);
+
+        if ($aNeg !== $bNeg) {
+            $result = $this->neg($result);
+        }
+
+        return $result;
+    }
+
+    #[Override]
+    public function divQ(string $a, string $b): string
+    {
+        return $this->divQR($a, $b)[0];
+    }
+
+    #[Override]
+    public function divR(string $a, string $b): string
+    {
+        return $this->divQR($a, $b)[1];
+    }
+
+    #[Override]
+    public function divQR(string $a, string $b): array
+    {
+        if ($a === '0') {
+            return ['0', '0'];
+        }
+
+        if ($a === $b) {
+            return ['1', '0'];
+        }
+
+        if ($b === '1') {
+            return [$a, '0'];
+        }
+
+        if ($b === '-1') {
+            return [$this->neg($a), '0'];
+        }
+
+        /** @var numeric-string $a */
+        $na = $a * 1; // cast to number
+
+        if (is_int($na)) {
+            /** @var numeric-string $b */
+            $nb = $b * 1;
+
+            if (is_int($nb)) {
+                // the only division that may overflow is PHP_INT_MIN / -1,
+                // which cannot happen here as we've already handled a divisor of -1 above.
+                $q = intdiv($na, $nb);
+                $r = $na % $nb;
+
+                return [
+                    (string) $q,
+                    (string) $r,
+                ];
+            }
+        }
+
+        [$aNeg, $bNeg, $aDig, $bDig] = $this->init($a, $b);
+
+        [$q, $r] = $this->doDiv($aDig, $bDig);
+
+        if ($aNeg !== $bNeg) {
+            $q = $this->neg($q);
+        }
+
+        if ($aNeg) {
+            $r = $this->neg($r);
+        }
+
+        return [$q, $r];
+    }
+
+    #[Override]
+    public function pow(string $a, int $e): string
+    {
+        if ($e === 0) {
+            return '1';
+        }
+
+        if ($e === 1) {
+            return $a;
+        }
+
+        $odd = $e % 2;
+        $e -= $odd;
+
+        $aa = $this->mul($a, $a);
+
+        $result = $this->pow($aa, $e / 2);
+
+        if ($odd === 1) {
+            $result = $this->mul($result, $a);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Algorithm from: https://www.geeksforgeeks.org/modular-exponentiation-power-in-modular-arithmetic/.
+     */
+    #[Override]
+    public function modPow(string $base, string $exp, string $mod): string
+    {
+        // normalize to Euclidean representative so modPow() stays consistent with mod()
+        $base = $this->mod($base, $mod);
+
+        // special case: the algorithm below fails with power 0 mod 1 (returns 1 instead of 0)
+        if ($exp === '0' && $mod === '1') {
+            return '0';
+        }
+
+        $x = $base;
+
+        $res = '1';
+
+        // numbers are positive, so we can use remainder instead of modulo
+        $x = $this->divR($x, $mod);
+
+        while ($exp !== '0') {
+            if (in_array($exp[-1], ['1', '3', '5', '7', '9'])) { // odd
+                $res = $this->divR($this->mul($res, $x), $mod);
+            }
+
+            $exp = $this->divQ($exp, '2');
+            $x = $this->divR($this->mul($x, $x), $mod);
+        }
+
+        return $res;
+    }
+
+    /**
+     * Adapted from https://cp-algorithms.com/num_methods/roots_newton.html.
+     */
+    #[Override]
+    public function sqrt(string $n): string
+    {
+        if ($n === '0') {
+            return '0';
+        }
+
+        // initial approximation
+        $x = str_repeat('9', intdiv(strlen($n), 2) ?: 1);
+
+        $decreased = false;
+
+        for (; ;) {
+            $nx = $this->divQ($this->add($x, $this->divQ($n, $x)), '2');
+
+            if ($x === $nx || $this->cmp($nx, $x) > 0 && $decreased) {
+                break;
+            }
+
+            $decreased = $this->cmp($nx, $x) < 0;
+            $x = $nx;
+        }
+
+        return $x;
+    }
+
+    /**
+     * Performs the addition of two non-signed large integers.
+     *
+     * @pure
+     */
+    private function doAdd(string $a, string $b): string
+    {
+        [$a, $b, $length] = $this->pad($a, $b);
+
+        $carry = 0;
+        $result = '';
+
+        for ($i = $length - $this->maxDigits; ; $i -= $this->maxDigits) {
+            $blockLength = $this->maxDigits;
+
+            if ($i < 0) {
+                $blockLength += $i;
+                $i = 0;
+            }
+
+            /** @var numeric-string $blockA */
+            $blockA = substr($a, $i, $blockLength);
+
+            /** @var numeric-string $blockB */
+            $blockB = substr($b, $i, $blockLength);
+
+            $sum = (string) ($blockA + $blockB + $carry);
+            $sumLength = strlen($sum);
+
+            if ($sumLength > $blockLength) {
+                $sum = substr($sum, 1);
+                $carry = 1;
+            } else {
+                if ($sumLength < $blockLength) {
+                    $sum = str_repeat('0', $blockLength - $sumLength) . $sum;
+                }
+                $carry = 0;
+            }
+
+            $result = $sum . $result;
+
+            if ($i === 0) {
+                break;
+            }
+        }
+
+        if ($carry === 1) {
+            $result = '1' . $result;
+        }
+
+        return $result;
+    }
+
+    /**
+     * Performs the subtraction of two non-signed large integers.
+     *
+     * @pure
+     */
+    private function doSub(string $a, string $b): string
+    {
+        if ($a === $b) {
+            return '0';
+        }
+
+        // Ensure that we always subtract to a positive result: biggest minus smallest.
+        $cmp = $this->doCmp($a, $b);
+
+        $invert = ($cmp === -1);
+
+        if ($invert) {
+            $c = $a;
+            $a = $b;
+            $b = $c;
+        }
+
+        [$a, $b, $length] = $this->pad($a, $b);
+
+        $carry = 0;
+        $result = '';
+
+        $complement = 10 ** $this->maxDigits;
+
+        for ($i = $length - $this->maxDigits; ; $i -= $this->maxDigits) {
+            $blockLength = $this->maxDigits;
+
+            if ($i < 0) {
+                $blockLength += $i;
+                $i = 0;
+            }
+
+            /** @var numeric-string $blockA */
+            $blockA = substr($a, $i, $blockLength);
+
+            /** @var numeric-string $blockB */
+            $blockB = substr($b, $i, $blockLength);
+
+            $sum = $blockA - $blockB - $carry;
+
+            if ($sum < 0) {
+                $sum += $complement;
+                $carry = 1;
+            } else {
+                $carry = 0;
+            }
+
+            $sum = (string) $sum;
+            $sumLength = strlen($sum);
+
+            if ($sumLength < $blockLength) {
+                $sum = str_repeat('0', $blockLength - $sumLength) . $sum;
+            }
+
+            $result = $sum . $result;
+
+            if ($i === 0) {
+                break;
+            }
+        }
+
+        // Carry cannot be 1 when the loop ends, as a > b
+        assert($carry === 0);
+
+        $result = ltrim($result, '0');
+
+        if ($invert) {
+            $result = $this->neg($result);
+        }
+
+        return $result;
+    }
+
+    /**
+     * Performs the multiplication of two non-signed large integers.
+     *
+     * @pure
+     */
+    private function doMul(string $a, string $b): string
+    {
+        $x = strlen($a);
+        $y = strlen($b);
+
+        $maxDigits = intdiv($this->maxDigits, 2);
+        $complement = 10 ** $maxDigits;
+
+        $result = '0';
+
+        for ($i = $x - $maxDigits; ; $i -= $maxDigits) {
+            $blockALength = $maxDigits;
+
+            if ($i < 0) {
+                $blockALength += $i;
+                $i = 0;
+            }
+
+            $blockA = (int) substr($a, $i, $blockALength);
+
+            $line = '';
+            $carry = 0;
+
+            for ($j = $y - $maxDigits; ; $j -= $maxDigits) {
+                $blockBLength = $maxDigits;
+
+                if ($j < 0) {
+                    $blockBLength += $j;
+                    $j = 0;
+                }
+
+                $blockB = (int) substr($b, $j, $blockBLength);
+
+                $mul = $blockA * $blockB + $carry;
+                $value = $mul % $complement;
+                $carry = ($mul - $value) / $complement;
+
+                $value = (string) $value;
+                $value = str_pad($value, $maxDigits, '0', STR_PAD_LEFT);
+
+                $line = $value . $line;
+
+                if ($j === 0) {
+                    break;
+                }
+            }
+
+            if ($carry !== 0) {
+                $line = $carry . $line;
+            }
+
+            $line = ltrim($line, '0');
+
+            if ($line !== '') {
+                $line .= str_repeat('0', $x - $blockALength - $i);
+                $result = $this->add($result, $line);
+            }
+
+            if ($i === 0) {
+                break;
+            }
+        }
+
+        return $result;
+    }
+
+    /**
+     * Performs the division of two non-signed large integers.
+     *
+     * @return string[] The quotient and remainder.
+     *
+     * @pure
+     */
+    private function doDiv(string $a, string $b): array
+    {
+        $cmp = $this->doCmp($a, $b);
+
+        if ($cmp === -1) {
+            return ['0', $a];
+        }
+
+        $x = strlen($a);
+        $y = strlen($b);
+
+        // we now know that a >= b && x >= y
+
+        $q = '0'; // quotient
+        $r = $a; // remainder
+        $z = $y; // focus length, always $y or $y+1
+
+        /** @var numeric-string $b */
+        $nb = $b * 1; // cast to number
+        // performance optimization in cases where the remainder will never cause int overflow
+        if (is_int(($nb - 1) * 10 + 9)) {
+            $r = (int) substr($a, 0, $z - 1);
+
+            for ($i = $z - 1; $i < $x; $i++) {
+                $n = $r * 10 + (int) $a[$i];
+                /** @var int $nb */
+                $q .= intdiv($n, $nb);
+                $r = $n % $nb;
+            }
+
+            return [ltrim($q, '0') ?: '0', (string) $r];
+        }
+
+        for (; ;) {
+            $focus = substr($a, 0, $z);
+
+            $cmp = $this->doCmp($focus, $b);
+
+            if ($cmp === -1) {
+                if ($z === $x) { // remainder < dividend
+                    break;
+                }
+
+                $z++;
+            }
+
+            $zeros = str_repeat('0', $x - $z);
+
+            $q = $this->add($q, '1' . $zeros);
+            $a = $this->sub($a, $b . $zeros);
+
+            $r = $a;
+
+            if ($r === '0') { // remainder == 0
+                break;
+            }
+
+            $x = strlen($a);
+
+            if ($x < $y) { // remainder < dividend
+                break;
+            }
+
+            $z = $y;
+        }
+
+        return [$q, $r];
+    }
+
+    /**
+     * Compares two non-signed large numbers.
+     *
+     * @return -1|0|1
+     *
+     * @pure
+     */
+    private function doCmp(string $a, string $b): int
+    {
+        $x = strlen($a);
+        $y = strlen($b);
+
+        $cmp = $x <=> $y;
+
+        if ($cmp !== 0) {
+            return $cmp;
+        }
+
+        return strcmp($a, $b) <=> 0; // enforce -1|0|1
+    }
+
+    /**
+     * Pads the left of one of the given numbers with zeros if necessary to make both numbers the same length.
+     *
+     * The numbers must only consist of digits, without leading minus sign.
+     *
+     * @return array{string, string, int}
+     *
+     * @pure
+     */
+    private function pad(string $a, string $b): array
+    {
+        $x = strlen($a);
+        $y = strlen($b);
+
+        if ($x > $y) {
+            $b = str_repeat('0', $x - $y) . $b;
+
+            return [$a, $b, $x];
+        }
+
+        if ($x < $y) {
+            $a = str_repeat('0', $y - $x) . $a;
+
+            return [$a, $b, $y];
+        }
+
+        return [$a, $b, $x];
+    }
+}

vendor/brick/math/src/Internal/CalculatorRegistry.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal;
+
+use function extension_loaded;
+
+/**
+ * Stores the current Calculator instance used by BigNumber classes.
+ *
+ * @internal
+ */
+final class CalculatorRegistry
+{
+    /**
+     * The Calculator instance in use.
+     */
+    private static ?Calculator $instance = null;
+
+    /**
+     * Sets the Calculator instance to use.
+     *
+     * An instance is typically set only in unit tests: autodetect is usually the best option.
+     *
+     * @param Calculator|null $calculator The calculator instance, or null to revert to autodetect.
+     */
+    final public static function set(?Calculator $calculator): void
+    {
+        self::$instance = $calculator;
+    }
+
+    /**
+     * Returns the Calculator instance to use.
+     *
+     * If none has been explicitly set, the fastest available implementation will be returned.
+     *
+     * Note: even though this method is not technically pure, it is considered pure when used in a normal context, when
+     * only relying on autodetect.
+     *
+     * @pure
+     */
+    final public static function get(): Calculator
+    {
+        /** @phpstan-ignore impure.staticPropertyAccess */
+        if (self::$instance === null) {
+            /** @phpstan-ignore impure.propertyAssign */
+            self::$instance = self::detect();
+        }
+
+        /** @phpstan-ignore impure.staticPropertyAccess */
+        return self::$instance;
+    }
+
+    /**
+     * Returns the fastest available Calculator implementation.
+     *
+     * @pure
+     *
+     * @codeCoverageIgnore
+     */
+    private static function detect(): Calculator
+    {
+        if (extension_loaded('gmp')) {
+            return new Calculator\GmpCalculator();
+        }
+
+        if (extension_loaded('bcmath')) {
+            return new Calculator\BcMathCalculator();
+        }
+
+        return new Calculator\NativeCalculator();
+    }
+}

vendor/brick/math/src/Internal/DecimalHelper.php

@@ -0,0 +1,177 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal;
+
+use Brick\Math\RoundingMode;
+
+use function ltrim;
+use function rtrim;
+use function str_pad;
+use function str_repeat;
+use function strlen;
+use function substr;
+
+use const STR_PAD_LEFT;
+
+/**
+ * Shared helper for decimal operations.
+ *
+ * @internal
+ */
+final class DecimalHelper
+{
+    private function __construct()
+    {
+    }
+
+    /**
+     * Computes the scale needed to represent the exact decimal result of a reduced fraction.
+     *
+     * Returns null if the denominator has prime factors other than 2 or 5.
+     *
+     * @param string $denominator The denominator of the reduced fraction. Must be strictly positive.
+     *
+     * @return non-negative-int|null
+     *
+     * @pure
+     */
+    public static function computeScaleFromReducedFractionDenominator(string $denominator): ?int
+    {
+        $calculator = CalculatorRegistry::get();
+
+        $d = rtrim($denominator, '0');
+
+        /** @var non-negative-int $scale rtrim can only shorten a string */
+        $scale = strlen($denominator) - strlen($d);
+
+        foreach ([5, 2] as $prime) {
+            for (; ;) {
+                $lastDigit = (int) $d[-1];
+
+                if ($lastDigit % $prime !== 0) {
+                    break;
+                }
+
+                $d = $calculator->divQ($d, (string) $prime);
+                $scale++;
+            }
+        }
+
+        return $d === '1' ? $scale : null;
+    }
+
+    /**
+     * Scales an unscaled decimal value to the requested scale.
+     *
+     * Returns null when rounding is necessary and the rounding mode is Unnecessary.
+     *
+     * @param string       $value        The unscaled value.
+     * @param int          $currentScale The current scale.
+     * @param int          $targetScale  The target scale.
+     * @param RoundingMode $roundingMode The rounding mode.
+     *
+     * @return string|null The unscaled value at the target scale, or null if RoundingMode::Unnecessary is used and rounding is necessary.
+     *
+     * @pure
+     */
+    public static function scale(string $value, int $currentScale, int $targetScale, RoundingMode $roundingMode): ?string
+    {
+        $scaled = self::tryScaleExactly($value, $currentScale, $targetScale);
+
+        if ($scaled !== null) {
+            return $scaled;
+        }
+
+        if ($roundingMode === RoundingMode::Unnecessary) {
+            return null;
+        }
+
+        $divisor = '1' . str_repeat('0', $currentScale - $targetScale);
+
+        return CalculatorRegistry::get()->divRound($value, $divisor, $roundingMode);
+    }
+
+    /**
+     * Adds leading zeros if necessary to represent the full decimal number.
+     *
+     * @param string $value The unscaled value.
+     * @param int    $scale The current scale.
+     *
+     * @pure
+     */
+    public static function padUnscaledValue(string $value, int $scale): string
+    {
+        $targetLength = $scale + 1;
+        $negative = ($value[0] === '-');
+        $length = strlen($value);
+
+        if ($negative) {
+            $length--;
+        }
+
+        if ($length >= $targetLength) {
+            return $value;
+        }
+
+        if ($negative) {
+            $value = substr($value, 1);
+        }
+
+        $value = str_pad($value, $targetLength, '0', STR_PAD_LEFT);
+
+        if ($negative) {
+            $value = '-' . $value;
+        }
+
+        return $value;
+    }
+
+    /**
+     * Tries to scale exactly without rounding, returning null when rounding would be required.
+     *
+     * @param string $value        The unscaled value.
+     * @param int    $currentScale The current scale.
+     * @param int    $targetScale  The target scale.
+     *
+     * @return string|null The unscaled value at the target scale, or null if rounding would be required.
+     *
+     * @pure
+     */
+    public static function tryScaleExactly(string $value, int $currentScale, int $targetScale): ?string
+    {
+        if ($value === '0' || $targetScale === $currentScale) {
+            return $value;
+        }
+
+        if ($targetScale > $currentScale) {
+            return $value . str_repeat('0', $targetScale - $currentScale);
+        }
+
+        $negative = ($value[0] === '-');
+        if ($negative) {
+            $value = substr($value, 1);
+        }
+
+        $value = self::padUnscaledValue($value, $currentScale);
+        $discardedDigits = $currentScale - $targetScale;
+
+        if (substr($value, -$discardedDigits) !== str_repeat('0', $discardedDigits)) {
+            return null;
+        }
+
+        $value = substr($value, 0, -$discardedDigits);
+        $value = ltrim($value, '0');
+
+        if ($value === '') {
+            return '0';
+        }
+
+        if ($negative) {
+            $value = '-' . $value;
+        }
+
+        return $value;
+    }
+}

vendor/brick/math/src/Internal/Safe.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Math\Internal;
+
+use Brick\Math\Exception\IntegerOverflowException;
+
+use function is_int;
+use function sprintf;
+
+use const PHP_INT_MIN;
+
+/**
+ * Helpers for arithmetic operations that throw on native integer overflow.
+ *
+ * @internal
+ */
+final class Safe
+{
+    private function __construct()
+    {
+    }
+
+    /**
+     * @pure
+     */
+    public static function add(int $a, int $b): int
+    {
+        $result = $a + $b;
+
+        if (is_int($result)) {
+            return $result;
+        }
+
+        // @phpstan-ignore deadCode.unreachable
+        throw IntegerOverflowException::nativeIntegerOverflow(sprintf('%d + %d', $a, $b));
+    }
+
+    /**
+     * @pure
+     */
+    public static function sub(int $a, int $b): int
+    {
+        $result = $a - $b;
+
+        if (is_int($result)) {
+            return $result;
+        }
+
+        // @phpstan-ignore deadCode.unreachable
+        throw IntegerOverflowException::nativeIntegerOverflow(sprintf('%d - %d', $a, $b));
+    }
+
+    /**
+     * @pure
+     */
+    public static function mul(int $a, int $b): int
+    {
+        $result = $a * $b;
+
+        if (is_int($result)) {
+            return $result;
+        }
+
+        // @phpstan-ignore deadCode.unreachable
+        throw IntegerOverflowException::nativeIntegerOverflow(sprintf('%d * %d', $a, $b));
+    }
+
+    /**
+     * @pure
+     */
+    public static function neg(int $value): int
+    {
+        if ($value === PHP_INT_MIN) {
+            throw IntegerOverflowException::nativeIntegerOverflow(sprintf('-(%d)', $value));
+        }
+
+        return -$value;
+    }
+}