Files
parsaaghayi-backend/vendor/brick/math/src/BigInteger.php
T
parsa aghaei 640bd67556
Deploy Backend / deploy (push) Failing after 1m13s
chore: commit vendor for offline build
2026-06-28 16:47:17 +03:30

1477 lines
46 KiB
PHP
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<?php
declare(strict_types=1);
namespace Brick\Math;
use Brick\Math\Exception\DivisionByZeroException;
use Brick\Math\Exception\IntegerOverflowException;
use Brick\Math\Exception\InvalidArgumentException;
use Brick\Math\Exception\MathException;
use Brick\Math\Exception\NegativeNumberException;
use Brick\Math\Exception\NoInverseException;
use Brick\Math\Exception\NumberFormatException;
use Brick\Math\Exception\RandomSourceException;
use Brick\Math\Exception\RoundingNecessaryException;
use Brick\Math\Internal\Calculator;
use Brick\Math\Internal\CalculatorRegistry;
use Brick\Math\Internal\Safe;
use LogicException;
use Override;
use Throwable;
use function array_map;
use function assert;
use function bin2hex;
use function chr;
use function count_chars;
use function filter_var;
use function hex2bin;
use function in_array;
use function intdiv;
use function is_string;
use function ltrim;
use function ord;
use function preg_match;
use function preg_quote;
use function random_bytes;
use function str_repeat;
use function strlen;
use function substr;
use const FILTER_VALIDATE_INT;
/**
* An arbitrarily large integer number.
*
* This class is immutable.
*/
final readonly class BigInteger extends BigNumber
{
/**
* The value, as a string of digits with optional leading minus sign.
*
* No leading zeros must be present.
* No leading minus sign must be present if the number is zero.
*/
private string $value;
/**
* Protected constructor. Use a factory method to obtain an instance.
*
* @param string $value A string of digits, with optional leading minus sign.
*
* @pure
*/
protected function __construct(string $value)
{
$this->value = $value;
}
/**
* Creates a number from a string in a given base.
*
* The string can optionally be prefixed with the `+` or `-` sign.
*
* Bases greater than 36 are not supported by this method, as there is no clear consensus on which of the lowercase
* or uppercase characters should come first. Instead, this method accepts any base up to 36, and does not
* differentiate lowercase and uppercase characters, which are considered equal.
*
* For bases greater than 36, and/or custom alphabets, use the fromArbitraryBase() method.
*
* @param non-empty-string $number The number to convert, in the given base.
* @param int<2, 36> $base The base of the number, between 2 and 36.
*
* @throws NumberFormatException If the number is empty, or contains invalid chars for the given base.
* @throws InvalidArgumentException If the base is out of range.
*
* @pure
*/
public static function fromBase(string $number, int $base): BigInteger
{
if ($base < 2 || $base > 36) { // @phpstan-ignore smaller.alwaysFalse, greater.alwaysFalse, booleanOr.alwaysFalse
throw InvalidArgumentException::baseOutOfRange($base);
}
if ($number === '') { // @phpstan-ignore identical.alwaysFalse
throw NumberFormatException::emptyNumber();
}
$originalNumber = $number;
if ($number[0] === '-') {
$sign = '-';
$number = substr($number, 1);
} elseif ($number[0] === '+') {
$sign = '';
$number = substr($number, 1);
} else {
$sign = '';
}
if ($number === '') {
throw NumberFormatException::invalidFormat($originalNumber);
}
$number = ltrim($number, '0');
if ($number === '') {
// The result will be the same in any base, avoid further calculation.
return BigInteger::zero();
}
if ($number === '1') {
// The result will be the same in any base, avoid further calculation.
return new BigInteger($sign . '1');
}
$pattern = '/[^' . substr(Calculator::ALPHABET, 0, $base) . ']/i';
if (preg_match($pattern, $number, $matches) === 1) {
throw NumberFormatException::charNotValidInBase($matches[0], $base);
}
if ($base === 10) {
// The number is usable as is, avoid further calculation.
return new BigInteger($sign . $number);
}
$result = CalculatorRegistry::get()->fromBase($number, $base);
return new BigInteger($sign . $result);
}
/**
* Parses a string containing an integer in an arbitrary base, using a custom alphabet.
*
* This method is byte-oriented: the alphabet is interpreted as a sequence of single-byte characters.
* Multibyte UTF-8 characters are not supported.
*
* Because this method accepts any single-byte character, including dash, it does not handle negative numbers.
*
* @param non-empty-string $number The number to parse.
* @param non-empty-string $alphabet The alphabet, for example '01' for base 2, or '01234567' for base 8.
*
* @throws NumberFormatException If the given number is empty or contains invalid chars for the given alphabet.
* @throws InvalidArgumentException If the alphabet does not contain at least 2 chars, or contains duplicates.
*
* @pure
*/
public static function fromArbitraryBase(string $number, string $alphabet): BigInteger
{
$base = strlen($alphabet);
if ($base < 2) {
throw InvalidArgumentException::alphabetTooShort();
}
if (strlen(count_chars($alphabet, 3)) !== $base) {
throw InvalidArgumentException::duplicateCharsInAlphabet();
}
if ($number === '') { // @phpstan-ignore identical.alwaysFalse
throw NumberFormatException::emptyNumber();
}
$pattern = '/[^' . preg_quote($alphabet, '/') . ']/';
if (preg_match($pattern, $number, $matches) === 1) {
throw NumberFormatException::charNotInAlphabet($matches[0]);
}
$number = CalculatorRegistry::get()->fromArbitraryBase($number, $alphabet, $base);
return new BigInteger($number);
}
/**
* Translates a string of bytes containing the binary representation of a BigInteger into a BigInteger.
*
* The input string is assumed to be in big-endian byte-order: the most significant byte is in the zeroth element.
*
* If `$signed` is true, the input is assumed to be in two's-complement representation, and the leading bit is
* interpreted as a sign bit. If `$signed` is false, the input is interpreted as an unsigned number, and the
* resulting BigInteger will always be positive or zero.
*
* This method can be used to retrieve a number exported by `toBytes()`, as long as the `$signed` flags match.
*
* @param non-empty-string $bytes The byte string.
* @param bool $signed Whether to interpret as a signed number in two's-complement representation with a leading
* sign bit.
*
* @throws NumberFormatException If the string is empty.
*
* @pure
*/
public static function fromBytes(string $bytes, bool $signed = true): BigInteger
{
if ($bytes === '') { // @phpstan-ignore identical.alwaysFalse
throw NumberFormatException::emptyByteString();
}
$twosComplement = false;
if ($signed) {
$x = ord($bytes[0]);
if (($twosComplement = ($x >= 0x80))) {
$bytes = ~$bytes;
}
}
$number = self::fromBase(bin2hex($bytes), 16);
if ($twosComplement) {
return $number->plus(1)->negated();
}
return $number;
}
/**
* Generates a pseudo-random number in the range 0 to 2^bitCount - 1.
*
* Using the default random bytes generator, this method is suitable for cryptographic use.
*
* @param non-negative-int $bitCount The number of bits.
* @param (callable(int): string)|null $randomBytesGenerator A function that accepts a number of bytes, and returns
* a string of random bytes of the given length. Defaults
* to the `random_bytes()` function.
*
* @throws InvalidArgumentException If $bitCount is negative.
* @throws RandomSourceException If random byte generation fails.
*/
public static function randomBits(int $bitCount, ?callable $randomBytesGenerator = null): BigInteger
{
if ($bitCount < 0) { // @phpstan-ignore smaller.alwaysFalse
throw InvalidArgumentException::negativeBitCount();
}
if ($bitCount === 0) {
return BigInteger::zero();
}
/** @var int<1, max> $byteLength */
$byteLength = intdiv($bitCount - 1, 8) + 1;
$extraBits = ($byteLength * 8 - $bitCount);
$bitmask = chr(0xFF >> $extraBits);
$randomBytes = self::randomBytes($byteLength, $randomBytesGenerator);
$randomBytes[0] = $randomBytes[0] & $bitmask;
return self::fromBytes($randomBytes, false);
}
/**
* Generates a pseudo-random number between `$min` and `$max`, inclusive.
*
* Using the default random bytes generator, this method is suitable for cryptographic use.
*
* @param BigNumber|int|string $min The lower bound. Must be convertible to a BigInteger.
* @param BigNumber|int|string $max The upper bound. Must be convertible to a BigInteger.
* @param (callable(int): string)|null $randomBytesGenerator A function that accepts a number of bytes, and returns
* a string of random bytes of the given length. Defaults
* to the `random_bytes()` function.
*
* @throws MathException If one of the parameters cannot be converted to a BigInteger.
* @throws InvalidArgumentException If `$min` is greater than `$max`.
* @throws RandomSourceException If random byte generation fails.
*/
public static function randomRange(
BigNumber|int|string $min,
BigNumber|int|string $max,
?callable $randomBytesGenerator = null,
): BigInteger {
$min = BigInteger::of($min);
$max = BigInteger::of($max);
if ($min->isGreaterThan($max)) {
throw InvalidArgumentException::minGreaterThanMax();
}
if ($min->isEqualTo($max)) {
return $min;
}
$diff = $max->minus($min);
$bitLength = $diff->getBitLength();
// try until the number is in range (50% to 100% chance of success)
do {
$randomNumber = self::randomBits($bitLength, $randomBytesGenerator);
} while ($randomNumber->isGreaterThan($diff));
return $randomNumber->plus($min);
}
/**
* Returns a BigInteger representing zero.
*
* @pure
*/
public static function zero(): BigInteger
{
/** @var BigInteger|null $zero */
static $zero;
if ($zero === null) {
$zero = new BigInteger('0');
}
return $zero;
}
/**
* Returns a BigInteger representing one.
*
* @pure
*/
public static function one(): BigInteger
{
/** @var BigInteger|null $one */
static $one;
if ($one === null) {
$one = new BigInteger('1');
}
return $one;
}
/**
* Returns a BigInteger representing ten.
*
* @pure
*/
public static function ten(): BigInteger
{
/** @var BigInteger|null $ten */
static $ten;
if ($ten === null) {
$ten = new BigInteger('10');
}
return $ten;
}
/**
* Returns the greatest common divisor of the given numbers.
*
* The GCD is always positive, unless all numbers are zero, in which case it is zero.
*
* @param BigNumber|int|string $a The first number. Must be convertible to a BigInteger.
* @param BigNumber|int|string ...$n The additional numbers. Each number must be convertible to a BigInteger.
*
* @throws MathException If one of the parameters cannot be converted to a BigInteger.
*
* @pure
*/
public static function gcdAll(BigNumber|int|string $a, BigNumber|int|string ...$n): BigInteger
{
$result = BigInteger::of($a)->abs();
$n = array_map(BigInteger::of(...), $n); // @phpstan-ignore possiblyImpure.functionCall
foreach ($n as $next) {
$result = $result->gcd($next);
if ($result->isEqualTo(1)) {
return $result;
}
}
return $result;
}
/**
* Returns the least common multiple of the given numbers.
*
* The LCM is always positive, unless one of the numbers is zero, in which case it is zero.
*
* @param BigNumber|int|string $a The first number. Must be convertible to a BigInteger.
* @param BigNumber|int|string ...$n The additional numbers. Each number must be convertible to a BigInteger.
*
* @throws MathException If one of the parameters cannot be converted to a BigInteger.
*
* @pure
*/
public static function lcmAll(BigNumber|int|string $a, BigNumber|int|string ...$n): BigInteger
{
$result = BigInteger::of($a)->abs();
$n = array_map(BigInteger::of(...), $n); // @phpstan-ignore possiblyImpure.functionCall
foreach ($n as $next) {
$result = $result->lcm($next);
if ($result->isZero()) {
return $result;
}
}
return $result;
}
/**
* Returns the sum of this number and the given one.
*
* @param BigNumber|int|string $that The number to add. Must be convertible to a BigInteger.
*
* @throws MathException If the number is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function plus(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($that->isZero()) {
return $this;
}
if ($this->isZero()) {
return $that;
}
$value = CalculatorRegistry::get()->add($this->value, $that->value);
return new BigInteger($value);
}
/**
* Returns the difference of this number and the given one.
*
* @param BigNumber|int|string $that The number to subtract. Must be convertible to a BigInteger.
*
* @throws MathException If the number is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function minus(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($that->isZero()) {
return $this;
}
if ($this->isZero()) {
return $that->negated();
}
$value = CalculatorRegistry::get()->sub($this->value, $that->value);
return new BigInteger($value);
}
/**
* Returns the product of this number and the given one.
*
* @param BigNumber|int|string $that The multiplier. Must be convertible to a BigInteger.
*
* @throws MathException If the multiplier is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function multipliedBy(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($that->isOne()) {
return $this;
}
if ($this->isOne()) {
return $that;
}
$value = CalculatorRegistry::get()->mul($this->value, $that->value);
return new BigInteger($value);
}
/**
* Returns the result of the division of this number by the given one.
*
* @param BigNumber|int|string $that The divisor. Must be convertible to a BigInteger.
* @param RoundingMode $roundingMode An optional rounding mode, defaults to Unnecessary.
*
* @throws MathException If the divisor is not valid, or is not convertible to a BigInteger.
* @throws DivisionByZeroException If the divisor is zero.
* @throws RoundingNecessaryException If RoundingMode::Unnecessary is used and the remainder is not zero.
*
* @pure
*/
public function dividedBy(BigNumber|int|string $that, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigInteger
{
$that = BigInteger::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
if ($that->isOne()) {
return $this;
}
if ($that->isMinusOne()) {
return $this->negated();
}
$result = CalculatorRegistry::get()->divRound($this->value, $that->value, $roundingMode);
if ($result === null) {
throw RoundingNecessaryException::integerDivisionNotExact();
}
return new BigInteger($result);
}
/**
* Returns this number exponentiated to the given value.
*
* @param non-negative-int $exponent
*
* @throws InvalidArgumentException If the exponent is negative.
*
* @pure
*/
public function power(int $exponent): BigInteger
{
if ($exponent === 0) {
return BigInteger::one();
}
if ($exponent === 1) {
return $this;
}
if ($exponent < 0) { // @phpstan-ignore smaller.alwaysFalse
throw InvalidArgumentException::negativeExponent();
}
return new BigInteger(CalculatorRegistry::get()->pow($this->value, $exponent));
}
/**
* Returns the quotient of the division of this number by the given one.
*
* Examples:
*
* - `7` quotient `3` returns `2`
* - `7` quotient `-3` returns `-2`
* - `-7` quotient `3` returns `-2`
* - `-7` quotient `-3` returns `2`
*
* @param BigNumber|int|string $that The divisor. Must be convertible to a BigInteger.
*
* @throws MathException If the divisor is not valid, or is not convertible to a BigInteger.
* @throws DivisionByZeroException If the divisor is zero.
*
* @pure
*/
public function quotient(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
if ($that->isOne()) {
return $this;
}
if ($that->isMinusOne()) {
return $this->negated();
}
$quotient = CalculatorRegistry::get()->divQ($this->value, $that->value);
return new BigInteger($quotient);
}
/**
* Returns the remainder of the division of this number by the given one.
*
* The remainder, when non-zero, has the same sign as the dividend.
*
* Examples:
*
* - `7` remainder `3` returns `1`
* - `7` remainder `-3` returns `1`
* - `-7` remainder `3` returns `-1`
* - `-7` remainder `-3` returns `-1`
*
* @param BigNumber|int|string $that The divisor. Must be convertible to a BigInteger.
*
* @throws MathException If the divisor is not valid, or is not convertible to a BigInteger.
* @throws DivisionByZeroException If the divisor is zero.
*
* @pure
*/
public function remainder(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
if ($that->isOne() || $that->isMinusOne()) {
return BigInteger::zero();
}
$remainder = CalculatorRegistry::get()->divR($this->value, $that->value);
return new BigInteger($remainder);
}
/**
* Returns the quotient and remainder of the division of this number by the given one.
*
* Examples:
*
* - `7` quotientAndRemainder `3` returns [`2`, `1`]
* - `7` quotientAndRemainder `-3` returns [`-2`, `1`]
* - `-7` quotientAndRemainder `3` returns [`-2`, `-1`]
* - `-7` quotientAndRemainder `-3` returns [`2`, `-1`]
*
* @param BigNumber|int|string $that The divisor. Must be convertible to a BigInteger.
*
* @return array{BigInteger, BigInteger} An array containing the quotient and the remainder.
*
* @throws MathException If the divisor is not valid, or is not convertible to a BigInteger.
* @throws DivisionByZeroException If the divisor is zero.
*
* @pure
*/
public function quotientAndRemainder(BigNumber|int|string $that): array
{
$that = BigInteger::of($that);
if ($that->isZero()) {
throw DivisionByZeroException::divisionByZero();
}
if ($that->isOne()) {
return [$this, BigInteger::zero()];
}
if ($that->isMinusOne()) {
return [$this->negated(), BigInteger::zero()];
}
[$quotient, $remainder] = CalculatorRegistry::get()->divQR($this->value, $that->value);
return [
new BigInteger($quotient),
new BigInteger($remainder),
];
}
/**
* Returns this number modulo the given one.
*
* The result is always non-negative, and is the unique value `r` such that `0 <= r < m`
* and `this - r` is a multiple of `m`.
*
* This is also known as Euclidean modulo. Unlike `remainder()`, which can return negative values
* when the dividend is negative, `mod()` always returns a non-negative result.
*
* Examples:
*
* - `7` mod `3` returns `1`
* - `-7` mod `3` returns `2`
*
* @param BigNumber|int|string $modulus The modulus. Must be convertible to a BigInteger.
*
* @throws MathException If the modulus is not valid, or is not convertible to a BigInteger.
* @throws InvalidArgumentException If the modulus is negative.
* @throws DivisionByZeroException If the modulus is zero.
*
* @pure
*/
public function mod(BigNumber|int|string $modulus): BigInteger
{
$modulus = BigInteger::of($modulus);
if ($modulus->isZero()) {
throw DivisionByZeroException::zeroModulus();
}
if ($modulus->isNegative()) {
throw InvalidArgumentException::negativeModulus();
}
$value = CalculatorRegistry::get()->mod($this->value, $modulus->value);
return new BigInteger($value);
}
/**
* Returns the modular multiplicative inverse of this BigInteger modulo $modulus.
*
* @param BigNumber|int|string $modulus The modulus. Must be convertible to a BigInteger.
*
* @throws MathException If the modulus is not valid, or is not convertible to a BigInteger.
* @throws InvalidArgumentException If the modulus is negative.
* @throws DivisionByZeroException If the modulus is zero.
* @throws NoInverseException If this BigInteger has no multiplicative inverse mod m (that is, this BigInteger
* is not relatively prime to m).
*
* @pure
*/
public function modInverse(BigNumber|int|string $modulus): BigInteger
{
$modulus = BigInteger::of($modulus);
if ($modulus->isZero()) {
throw DivisionByZeroException::zeroModulus();
}
if ($modulus->isNegative()) {
throw InvalidArgumentException::negativeModulus();
}
if ($modulus->isOne()) {
return BigInteger::zero();
}
$value = CalculatorRegistry::get()->modInverse($this->value, $modulus->value);
if ($value === null) {
throw NoInverseException::noModularInverse();
}
return new BigInteger($value);
}
/**
* Returns this number raised into power with modulo.
*
* This operation requires a non-negative exponent and a strictly positive modulus.
*
* @param BigNumber|int|string $exponent The exponent. Must be convertible to a BigInteger.
* @param BigNumber|int|string $modulus The modulus. Must be convertible to a BigInteger.
*
* @throws MathException If the exponent or modulus is not valid, or is not convertible to a BigInteger.
* @throws InvalidArgumentException If the exponent or modulus is negative.
* @throws DivisionByZeroException If the modulus is zero.
*
* @pure
*/
public function modPow(BigNumber|int|string $exponent, BigNumber|int|string $modulus): BigInteger
{
$exponent = BigInteger::of($exponent);
$modulus = BigInteger::of($modulus);
if ($modulus->isZero()) {
throw DivisionByZeroException::zeroModulus();
}
if ($modulus->isNegative()) {
throw InvalidArgumentException::negativeModulus();
}
if ($exponent->isNegative()) {
throw InvalidArgumentException::negativeExponent();
}
$result = CalculatorRegistry::get()->modPow($this->value, $exponent->value, $modulus->value);
return new BigInteger($result);
}
/**
* Returns the greatest common divisor of this number and the given one.
*
* The GCD is always positive, unless both operands are zero, in which case it is zero.
*
* @param BigNumber|int|string $that The operand. Must be convertible to a BigInteger.
*
* @throws MathException If the operand is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function gcd(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($that->isZero()) {
return $this->abs();
}
if ($this->isZero()) {
return $that->abs();
}
$value = CalculatorRegistry::get()->gcd($this->value, $that->value);
return new BigInteger($value);
}
/**
* Returns the least common multiple of this number and the given one.
*
* The LCM is always positive, unless at least one operand is zero, in which case it is zero.
*
* @param BigNumber|int|string $that The operand. Must be convertible to a BigInteger.
*
* @throws MathException If the operand is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function lcm(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
if ($this->isZero() || $that->isZero()) {
return BigInteger::zero();
}
$value = CalculatorRegistry::get()->lcm($this->value, $that->value);
return new BigInteger($value);
}
/**
* Returns the integer square root of this number, rounded according to the given rounding mode.
*
* @param RoundingMode $roundingMode An optional rounding mode, defaults to Unnecessary.
*
* @throws NegativeNumberException If this number is negative.
* @throws RoundingNecessaryException If RoundingMode::Unnecessary is used, and the number is not a perfect square.
*
* @pure
*/
public function sqrt(RoundingMode $roundingMode = RoundingMode::Unnecessary): BigInteger
{
if ($this->isNegative()) {
throw NegativeNumberException::squareRootOfNegativeNumber();
}
$calculator = CalculatorRegistry::get();
$sqrt = $calculator->sqrt($this->value);
// For Down and Floor (equivalent for non-negative numbers), return floor sqrt
if ($roundingMode === RoundingMode::Down || $roundingMode === RoundingMode::Floor) {
return new BigInteger($sqrt);
}
// Check if the sqrt is exact
$s2 = $calculator->mul($sqrt, $sqrt);
$remainder = $calculator->sub($this->value, $s2);
if ($remainder === '0') {
// sqrt is exact
return new BigInteger($sqrt);
}
// sqrt is not exact
if ($roundingMode === RoundingMode::Unnecessary) {
throw RoundingNecessaryException::integerSquareRootNotExact();
}
// For Up and Ceiling (equivalent for non-negative numbers), round up
if ($roundingMode === RoundingMode::Up || $roundingMode === RoundingMode::Ceiling) {
return new BigInteger($calculator->add($sqrt, '1'));
}
// For Half* modes, compare our number to the midpoint of the interval [s², (s+1)²[.
// The midpoint is s² + s + 0.5. Comparing n >= s² + s + 0.5 with remainder = n − s²
// is equivalent to comparing 2*remainder >= 2*s + 1.
$twoRemainder = $calculator->mul($remainder, '2');
$threshold = $calculator->add($calculator->mul($sqrt, '2'), '1');
$cmp = $calculator->cmp($twoRemainder, $threshold);
// We're supposed to increment (round up) when:
// - HalfUp, HalfCeiling => $cmp >= 0
// - HalfDown, HalfFloor => $cmp > 0
// - HalfEven => $cmp > 0 || ($cmp === 0 && $sqrt % 2 === 1)
// But 2*remainder is always even and 2*s + 1 is always odd, so $cmp is never zero.
// Therefore, all Half* modes simplify to:
if ($cmp > 0) {
$sqrt = $calculator->add($sqrt, '1');
}
return new BigInteger($sqrt);
}
/**
* Returns the integer nth root of this number, rounded according to the given rounding mode.
*
* For odd $n, the operation is defined for negative inputs: the sign is preserved and the
* magnitude of the root is |$this|^(1/$n).
*
* @param positive-int $n The root degree. Must be a strictly positive integer.
* @param RoundingMode $roundingMode An optional rounding mode, defaults to Unnecessary.
*
* @throws InvalidArgumentException If $n is less than 1.
* @throws NegativeNumberException If this number is negative and $n is even.
* @throws RoundingNecessaryException If RoundingMode::Unnecessary is used, and this number is not a perfect nth power.
*
* @pure
*/
public function nthRoot(int $n, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigInteger
{
if ($n < 1) { // @phpstan-ignore smaller.alwaysFalse
throw InvalidArgumentException::nonPositiveNthRootDegree();
}
if ($n === 1) {
return $this;
}
$isNegative = $this->isNegative();
if ($isNegative && $n % 2 === 0) {
throw NegativeNumberException::nthRootOfNegativeNumber();
}
$calculator = CalculatorRegistry::get();
// Truncation toward zero: for positive $this this is the floor root, for negative $this
// with odd $n this is the ceiling of the true root (i.e., the root of smaller magnitude).
$truncatedRoot = $calculator->nthRoot($this->value, $n);
$rootPow = $calculator->pow($truncatedRoot, $n);
if ($rootPow === $this->value) {
return new BigInteger($truncatedRoot);
}
if ($roundingMode === RoundingMode::Unnecessary) {
throw RoundingNecessaryException::integerNthRootNotExact();
}
$isPositive = ! $isNegative;
// The next-step root is one unit further from zero than the truncated root.
$nextStep = $isPositive
? $calculator->add($truncatedRoot, '1')
: $calculator->sub($truncatedRoot, '1');
if ($roundingMode === RoundingMode::Up) {
$increment = true;
} elseif ($roundingMode === RoundingMode::Down) {
$increment = false;
} elseif ($roundingMode === RoundingMode::Ceiling) {
$increment = $isPositive;
} elseif ($roundingMode === RoundingMode::Floor) {
$increment = ! $isPositive;
} else {
// Half* modes: increment iff |$this| > (|truncated| + 0.5)^n, equivalently
// 2^n * |$this| > (2*|truncated| + 1)^n. The rhs is odd while the lhs is even
// (n ≥ 2 here, so 2^n is even), so a midpoint tie is impossible and all five
// Half* modes collapse to the same comparison.
$absValue = $calculator->abs($this->value);
$absTruncated = $calculator->abs($truncatedRoot);
$twoAbsRootPlus1 = $calculator->add($calculator->mul($absTruncated, '2'), '1');
$lhs = $calculator->mul($calculator->pow('2', $n), $absValue);
$rhs = $calculator->pow($twoAbsRootPlus1, $n);
$increment = $calculator->cmp($lhs, $rhs) > 0;
}
return new BigInteger($increment ? $nextStep : $truncatedRoot);
}
#[Override]
public function negated(): static
{
return new BigInteger(CalculatorRegistry::get()->neg($this->value));
}
/**
* Returns the integer bitwise-and combined with another integer.
*
* This method returns a negative BigInteger if and only if both operands are negative.
*
* @param BigNumber|int|string $that The operand. Must be convertible to a BigInteger.
*
* @throws MathException If the operand is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function and(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
return new BigInteger(CalculatorRegistry::get()->and($this->value, $that->value));
}
/**
* Returns the integer bitwise-or combined with another integer.
*
* This method returns a negative BigInteger if and only if either of the operands is negative.
*
* @param BigNumber|int|string $that The operand. Must be convertible to a BigInteger.
*
* @throws MathException If the operand is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function or(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
return new BigInteger(CalculatorRegistry::get()->or($this->value, $that->value));
}
/**
* Returns the integer bitwise-xor combined with another integer.
*
* This method returns a negative BigInteger if and only if exactly one of the operands is negative.
*
* @param BigNumber|int|string $that The operand. Must be convertible to a BigInteger.
*
* @throws MathException If the operand is not valid, or is not convertible to a BigInteger.
*
* @pure
*/
public function xor(BigNumber|int|string $that): BigInteger
{
$that = BigInteger::of($that);
return new BigInteger(CalculatorRegistry::get()->xor($this->value, $that->value));
}
/**
* Returns the bitwise-not of this BigInteger.
*
* @pure
*/
public function not(): BigInteger
{
return $this->negated()->minus(1);
}
/**
* Returns the integer left shifted by a given number of bits.
*
* If $bits is negative, the integer is shifted right by the absolute value instead.
*
* @pure
*/
public function shiftedLeft(int $bits): BigInteger
{
if ($bits === 0) {
return $this;
}
if ($bits < 0) {
return $this->shiftedRight(Safe::neg($bits));
}
return $this->multipliedBy(BigInteger::of(2)->power($bits));
}
/**
* Returns the integer right shifted by a given number of bits.
*
* If $bits is negative, the integer is shifted left by the absolute value instead.
*
* @pure
*/
public function shiftedRight(int $bits): BigInteger
{
if ($bits === 0) {
return $this;
}
if ($bits < 0) {
return $this->shiftedLeft(Safe::neg($bits));
}
$operand = BigInteger::of(2)->power($bits);
if ($this->isPositiveOrZero()) {
return $this->quotient($operand);
}
return $this->dividedBy($operand, RoundingMode::Up);
}
/**
* Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit.
*
* For positive BigIntegers, this is equivalent to the number of bits in the ordinary binary representation.
* Computes (ceil(log2(this < 0 ? -this : this+1))).
*
* @return non-negative-int
*
* @pure
*/
public function getBitLength(): int
{
if ($this->isZero()) {
return 0;
}
if ($this->isNegative()) {
return $this->abs()->minus(1)->getBitLength();
}
return strlen($this->toBase(2));
}
/**
* Returns the index of the rightmost (lowest-order) one bit in this BigInteger.
*
* Returns null if this BigInteger is zero.
*
* @return non-negative-int|null
*
* @pure
*/
public function getLowestSetBit(): ?int
{
$n = $this;
$bitLength = $this->getBitLength();
for ($i = 0; $i <= $bitLength; $i++) {
if ($n->isOdd()) {
return $i;
}
$n = $n->shiftedRight(1);
}
return null;
}
/**
* Returns true if and only if the designated bit is set.
*
* Computes ((this & (1<<bitIndex)) != 0).
*
* @param non-negative-int $bitIndex The bit to test, 0-based.
*
* @throws InvalidArgumentException If the bit to test is negative.
*
* @pure
*/
public function isBitSet(int $bitIndex): bool
{
if ($bitIndex < 0) { // @phpstan-ignore smaller.alwaysFalse
throw InvalidArgumentException::negativeBitIndex();
}
return $this->shiftedRight($bitIndex)->isOdd();
}
/**
* Returns whether this number is even.
*
* @pure
*/
public function isEven(): bool
{
return in_array($this->value[-1], ['0', '2', '4', '6', '8'], true);
}
/**
* Returns whether this number is odd.
*
* @pure
*/
public function isOdd(): bool
{
return in_array($this->value[-1], ['1', '3', '5', '7', '9'], true);
}
#[Override]
public function compareTo(BigNumber|int|string $that): int
{
$that = BigNumber::of($that);
if ($that instanceof BigInteger) {
return CalculatorRegistry::get()->cmp($this->value, $that->value);
}
return -$that->compareTo($this);
}
#[Override]
public function getSign(): int
{
return ($this->value === '0') ? 0 : (($this->value[0] === '-') ? -1 : 1);
}
#[Override]
public function toBigInteger(): BigInteger
{
return $this;
}
#[Override]
public function toBigDecimal(): BigDecimal
{
return self::newBigDecimal($this->value);
}
#[Override]
public function toBigRational(): BigRational
{
return self::newBigRational($this, BigInteger::one(), false, false);
}
#[Override]
public function toScale(int $scale, RoundingMode $roundingMode = RoundingMode::Unnecessary): BigDecimal
{
return $this->toBigDecimal()->toScale($scale, $roundingMode);
}
#[Override]
public function toInt(): int
{
$intValue = filter_var($this->value, FILTER_VALIDATE_INT);
if ($intValue === false) {
throw IntegerOverflowException::integerOutOfRange($this);
}
return $intValue;
}
#[Override]
public function toFloat(): float
{
return (float) $this->value;
}
/**
* Returns a string representation of this number in the given base.
*
* The output will always be lowercase for bases greater than 10.
*
* @param int<2, 36> $base
*
* @return non-empty-string
*
* @throws InvalidArgumentException If the base is out of range.
*
* @pure
*/
public function toBase(int $base): string
{
if ($base === 10) {
/** @var non-empty-string */
return $this->value;
}
if ($base < 2 || $base > 36) { // @phpstan-ignore smaller.alwaysFalse, greater.alwaysFalse, booleanOr.alwaysFalse
throw InvalidArgumentException::baseOutOfRange($base);
}
/** @var non-empty-string */
return CalculatorRegistry::get()->toBase($this->value, $base);
}
/**
* Returns a string representation of this number in an arbitrary base with a custom alphabet.
*
* This method is byte-oriented: the alphabet is interpreted as a sequence of single-byte characters.
* Multibyte UTF-8 characters are not supported.
*
* Because this method accepts any single-byte character, including dash, it does not handle negative numbers;
* a NegativeNumberException will be thrown when attempting to call this method on a negative number.
*
* @param non-empty-string $alphabet The alphabet, for example '01' for base 2, or '01234567' for base 8.
*
* @return non-empty-string
*
* @throws InvalidArgumentException If the alphabet does not contain at least 2 chars, or contains duplicates.
* @throws NegativeNumberException If this number is negative.
*
* @pure
*/
public function toArbitraryBase(string $alphabet): string
{
$base = strlen($alphabet);
if ($base < 2) {
throw InvalidArgumentException::alphabetTooShort();
}
if (strlen(count_chars($alphabet, 3)) !== $base) {
throw InvalidArgumentException::duplicateCharsInAlphabet();
}
if ($this->isNegative()) {
throw NegativeNumberException::toArbitraryBaseOfNegativeNumber();
}
/** @var non-empty-string */
return CalculatorRegistry::get()->toArbitraryBase($this->value, $alphabet, $base);
}
/**
* Returns a string of bytes containing the binary representation of this BigInteger.
*
* The string is in big-endian byte-order: the most significant byte is in the zeroth element.
*
* If `$signed` is true, the output will be in two's-complement representation, and a sign bit will be prepended to
* the output. If `$signed` is false, no sign bit will be prepended, and this method will throw an exception if the
* number is negative.
*
* The string will contain the minimum number of bytes required to represent this BigInteger, including a sign bit
* if `$signed` is true.
*
* This representation is compatible with the `fromBytes()` factory method, as long as the `$signed` flags match.
*
* @param bool $signed Whether to output a signed number in two's-complement representation with a leading sign bit.
*
* @return non-empty-string
*
* @throws NegativeNumberException If $signed is false, and the number is negative.
*
* @pure
*/
public function toBytes(bool $signed = true): string
{
if (! $signed && $this->isNegative()) {
throw NegativeNumberException::unsignedBytesOfNegativeNumber();
}
$hex = $this->abs()->toBase(16);
if (strlen($hex) % 2 !== 0) {
$hex = '0' . $hex;
}
$baseHexLength = strlen($hex);
if ($signed) {
if ($this->isNegative()) {
$bin = hex2bin($hex);
assert($bin !== false);
/** @var non-empty-string $hex */
$hex = bin2hex(~$bin);
$hex = self::fromBase($hex, 16)->plus(1)->toBase(16);
$hexLength = strlen($hex);
if ($hexLength < $baseHexLength) {
$hex = str_repeat('0', $baseHexLength - $hexLength) . $hex;
}
if ($hex[0] < '8') {
$hex = 'FF' . $hex;
}
} else {
if ($hex[0] >= '8') {
$hex = '00' . $hex;
}
}
}
$result = hex2bin($hex);
assert($result !== false);
/** @var non-empty-string */
return $result;
}
/**
* @return numeric-string
*/
#[Override]
public function toString(): string
{
/** @var numeric-string */
return $this->value;
}
/**
* This method is required for serializing the object and SHOULD NOT be accessed directly.
*
* @internal
*
* @return array{value: string}
*/
public function __serialize(): array
{
return ['value' => $this->value];
}
/**
* This method is only here to allow unserializing the object and cannot be accessed directly.
*
* @internal
*
* @param array{value: string} $data
*
* @throws LogicException
*/
public function __unserialize(array $data): void
{
/** @phpstan-ignore isset.initializedProperty */
if (isset($this->value)) {
throw new LogicException('__unserialize() is an internal function, it must not be called directly.');
}
/** @phpstan-ignore deadCode.unreachable */
$this->value = $data['value'];
}
#[Override]
protected static function from(BigNumber $number): static
{
return $number->toBigInteger();
}
/**
* Returns random bytes from the provided generator or from random_bytes().
*
* @param int $byteLength The number of requested bytes.
* @param (callable(int): string)|null $randomBytesGenerator The random bytes generator, or null to use random_bytes().
*
* @throws RandomSourceException If random byte generation fails.
*/
private static function randomBytes(int $byteLength, ?callable $randomBytesGenerator): string
{
if ($randomBytesGenerator === null) {
$randomBytesGenerator = random_bytes(...);
}
try {
$randomBytes = $randomBytesGenerator($byteLength);
} catch (Throwable $e) {
throw RandomSourceException::randomSourceFailure($e);
}
/** @phpstan-ignore function.alreadyNarrowedType (Defensive runtime check for user-provided callbacks) */
if (! is_string($randomBytes)) {
throw RandomSourceException::invalidRandomBytesType($randomBytes);
}
if (strlen($randomBytes) !== $byteLength) {
throw RandomSourceException::invalidRandomBytesLength($byteLength, strlen($randomBytes));
}
return $randomBytes;
}
/**
* @pure
*/
private function isOne(): bool
{
return $this->value === '1';
}
/**
* @pure
*/
private function isMinusOne(): bool
{
return $this->value === '-1';
}
}