Documentation

BigInteger extends BigNumber
in package

An arbitrary-size integer.

All methods accepting a number as a parameter accept either a BigInteger instance, an integer, or a string representing an arbitrary size integer.

Tags
psalm-immutable

Table of Contents

PARSE_REGEXP  = '/^' . '(?<sign>[\\-\\+])?' . '(?:' . '(?:' . '(?<integral>[0-9]+)?' . '(?<point>\\.)?' . '(?<fractional>[0-9]+)?' . '(?:[eE](?<exponent>[\\-\\+]?[0-9]+))?' . ')|(?:' . '(?<numerator>[0-9]+)' . '\\/?' . '(?<denominator>[0-9]+)' . ')' . ')' . '$/'
The regular expression used to parse integer, decimal and rational numbers.
$value  : string
The value, as a string of digits with optional leading minus sign.
__toString()  : string
Returns a string representation of this number.
abs()  : BigInteger
Returns the absolute value of this number.
and()  : BigInteger
Returns the integer bitwise-and combined with another integer.
compareTo()  : int
Compares this number to the given one.
dividedBy()  : BigInteger
Returns the result of the division of this number by the given one.
fromArbitraryBase()  : BigInteger
Parses a string containing an integer in an arbitrary base, using a custom alphabet.
fromBase()  : BigInteger
Creates a number from a string in a given base.
fromBytes()  : BigInteger
Translates a string of bytes containing the binary representation of a BigInteger into a BigInteger.
gcd()  : BigInteger
Returns the greatest common divisor of this number and the given one.
getBitLength()  : int
Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit.
getLowestSetBit()  : int
Returns the index of the rightmost (lowest-order) one bit in this BigInteger.
getSign()  : int
Returns the sign of this number.
isEqualTo()  : bool
Checks if this number is equal to the given one.
isEven()  : bool
Returns whether this number is even.
isGreaterThan()  : bool
Checks if this number is strictly greater than the given one.
isGreaterThanOrEqualTo()  : bool
Checks if this number is greater than or equal to the given one.
isLessThan()  : bool
Checks if this number is strictly lower than the given one.
isLessThanOrEqualTo()  : bool
Checks if this number is lower than or equal to the given one.
isNegative()  : bool
Checks if this number is strictly negative.
isNegativeOrZero()  : bool
Checks if this number is negative or zero.
isOdd()  : bool
Returns whether this number is odd.
isPositive()  : bool
Checks if this number is strictly positive.
isPositiveOrZero()  : bool
Checks if this number is positive or zero.
isZero()  : bool
Checks if this number equals zero.
jsonSerialize()  : string
{@inheritdoc}
max()  : static
Returns the maximum of the given values.
min()  : static
Returns the minimum of the given values.
minus()  : BigInteger
Returns the difference of this number and the given one.
mod()  : BigInteger
Returns the modulo of this number and the given one.
modInverse()  : BigInteger
Returns the modular multiplicative inverse of this BigInteger modulo $m.
modPow()  : BigInteger
Returns this number raised into power with modulo.
multipliedBy()  : BigInteger
Returns the product of this number and the given one.
negated()  : BigInteger
Returns the inverse of this number.
not()  : BigInteger
Returns the bitwise-not of this BigInteger.
of()  : BigInteger
Creates a BigInteger of the given value.
one()  : BigInteger
Returns a BigInteger representing one.
or()  : BigInteger
Returns the integer bitwise-or combined with another integer.
plus()  : BigInteger
Returns the sum of this number and the given one.
power()  : BigInteger
Returns this number exponentiated to the given value.
quotient()  : BigInteger
Returns the quotient of the division of this number by the given one.
quotientAndRemainder()  : array<string|int, BigInteger>
Returns the quotient and remainder of the division of this number by the given one.
randomBits()  : BigInteger
Generates a pseudo-random number in the range 0 to 2^numBits - 1.
randomRange()  : BigInteger
Generates a pseudo-random number between `$min` and `$max`.
remainder()  : BigInteger
Returns the remainder of the division of this number by the given one.
shiftedLeft()  : BigInteger
Returns the integer left shifted by a given number of bits.
shiftedRight()  : BigInteger
Returns the integer right shifted by a given number of bits.
sqrt()  : BigInteger
Returns the integer square root number of this number, rounded down.
sum()  : static
Returns the sum of the given values.
ten()  : BigInteger
Returns a BigInteger representing ten.
testBit()  : bool
Returns true if and only if the designated bit is set.
toArbitraryBase()  : string
Returns a string representation of this number in an arbitrary base with a custom alphabet.
toBase()  : string
Returns a string representation of this number in the given base.
toBigDecimal()  : BigDecimal
Converts this number to a BigDecimal.
toBigInteger()  : BigInteger
Converts this number to a BigInteger.
toBigRational()  : BigRational
Converts this number to a BigRational.
toBytes()  : string
Returns a string of bytes containing the binary representation of this BigInteger.
toFloat()  : float
Returns an approximation of this number as a floating-point value.
toInt()  : int
Returns the exact value of this number as a native integer.
toScale()  : BigDecimal
Converts this number to a BigDecimal with the given scale, using rounding if necessary.
xor()  : BigInteger
Returns the integer bitwise-xor combined with another integer.
zero()  : BigInteger
Returns a BigInteger representing zero.
__construct()  : mixed
Protected constructor. Use a factory method to obtain an instance.
add()  : BigNumber
Adds two BigNumber instances in the correct order to avoid a RoundingNecessaryException.
cleanUp()  : string
Removes optional leading zeros and + sign from the given number.
floatToString()  : string
Safely converts float to string, avoiding locale-dependent issues.

Constants

PARSE_REGEXP

The regular expression used to parse integer, decimal and rational numbers.

private mixed PARSE_REGEXP = '/^' . '(?<sign>[\\-\\+])?' . '(?:' . '(?:' . '(?<integral>[0-9]+)?' . '(?<point>\\.)?' . '(?<fractional>[0-9]+)?' . '(?:[eE](?<exponent>[\\-\\+]?[0-9]+))?' . ')|(?:' . '(?<numerator>[0-9]+)' . '\\/?' . '(?<denominator>[0-9]+)' . ')' . ')' . '$/'

Properties

$value

The value, as a string of digits with optional leading minus sign.

private string $value

No leading zeros must be present. No leading minus sign must be present if the number is zero.

Methods

__toString()

Returns a string representation of this number.

public __toString() : string
Return values
string —

and()

Returns the integer bitwise-and combined with another integer.

public and(BigNumber|int|float|string $that) : BigInteger

This method returns a negative BigInteger if and only if both operands are negative.

Parameters
$that : BigNumber|int|float|string

The operand. Must be convertible to an integer number.

Return values
BigInteger —

compareTo()

Compares this number to the given one.

public compareTo(mixed $that) : int
Parameters
$that : mixed
Return values
int —

[-1,0,1] If $this is lower than, equal to, or greater than $that.

dividedBy()

Returns the result of the division of this number by the given one.

public dividedBy(BigNumber|int|float|string $that[, int $roundingMode = RoundingMode::UNNECESSARY ]) : BigInteger
Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigInteger.

$roundingMode : int = RoundingMode::UNNECESSARY

An optional rounding mode.

Tags
throws
MathException

If the divisor is not a valid number, is not convertible to a BigInteger, is zero, or RoundingMode::UNNECESSARY is used and the remainder is not zero.

Return values
BigInteger —

The result.

fromArbitraryBase()

Parses a string containing an integer in an arbitrary base, using a custom alphabet.

public static fromArbitraryBase(string $number, string $alphabet) : BigInteger

Because this method accepts an alphabet with any character, including dash, it does not handle negative numbers.

Parameters
$number : string

The number to parse.

$alphabet : string

The alphabet, for example '01' for base 2, or '01234567' for base 8.

Tags
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.

psalm-pure
Return values
BigInteger —

fromBase()

Creates a number from a string in a given base.

public static fromBase(string $number, int $base) : BigInteger

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.

Parameters
$number : string

The number to convert, in the given base.

$base : int

The base of the number, between 2 and 36.

Tags
throws
NumberFormatException

If the number is empty, or contains invalid chars for the given base.

throws
InvalidArgumentException

If the base is out of range.

psalm-pure
Return values
BigInteger —

fromBytes()

Translates a string of bytes containing the binary representation of a BigInteger into a BigInteger.

public static fromBytes(string $value[, bool $signed = true ]) : 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.

Parameters
$value : string

The byte string.

$signed : bool = true

Whether to interpret as a signed number in two's-complement representation with a leading sign bit.

Tags
throws
NumberFormatException

If the string is empty.

Return values
BigInteger —

gcd()

Returns the greatest common divisor of this number and the given one.

public gcd(BigNumber|int|float|string $that) : BigInteger

The GCD is always positive, unless both operands are zero, in which case it is zero.

Parameters
$that : BigNumber|int|float|string

The operand. Must be convertible to an integer number.

Return values
BigInteger —

getBitLength()

Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit.

public getBitLength() : int

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 values
int —

getLowestSetBit()

Returns the index of the rightmost (lowest-order) one bit in this BigInteger.

public getLowestSetBit() : int

Returns -1 if this BigInteger contains no one bits.

Return values
int —

getSign()

Returns the sign of this number.

public getSign() : int
Return values
int —

-1 if the number is negative, 0 if zero, 1 if positive.

isEqualTo()

Checks if this number is equal to the given one.

public isEqualTo(BigNumber|int|float|string $that) : bool
Parameters
$that : BigNumber|int|float|string
Return values
bool —

isEven()

Returns whether this number is even.

public isEven() : bool
Return values
bool —

isGreaterThan()

Checks if this number is strictly greater than the given one.

public isGreaterThan(BigNumber|int|float|string $that) : bool
Parameters
$that : BigNumber|int|float|string
Return values
bool —

isGreaterThanOrEqualTo()

Checks if this number is greater than or equal to the given one.

public isGreaterThanOrEqualTo(BigNumber|int|float|string $that) : bool
Parameters
$that : BigNumber|int|float|string
Return values
bool —

isLessThan()

Checks if this number is strictly lower than the given one.

public isLessThan(BigNumber|int|float|string $that) : bool
Parameters
$that : BigNumber|int|float|string
Return values
bool —

isLessThanOrEqualTo()

Checks if this number is lower than or equal to the given one.

public isLessThanOrEqualTo(BigNumber|int|float|string $that) : bool
Parameters
$that : BigNumber|int|float|string
Return values
bool —

isNegative()

Checks if this number is strictly negative.

public isNegative() : bool
Return values
bool —

isNegativeOrZero()

Checks if this number is negative or zero.

public isNegativeOrZero() : bool
Return values
bool —

isOdd()

Returns whether this number is odd.

public isOdd() : bool
Return values
bool —

isPositive()

Checks if this number is strictly positive.

public isPositive() : bool
Return values
bool —

isPositiveOrZero()

Checks if this number is positive or zero.

public isPositiveOrZero() : bool
Return values
bool —

isZero()

Checks if this number equals zero.

public isZero() : bool
Return values
bool —

jsonSerialize()

{@inheritdoc}

public jsonSerialize() : string
Return values
string —

max()

Returns the maximum of the given values.

public static max(BigNumber|int|float|string ...$values) : static
Parameters
$values : BigNumber|int|float|string

The numbers to compare. All the numbers need to be convertible to an instance of the class this method is called on.

Tags
throws
InvalidArgumentException

If no values are given.

throws
MathException

If an argument is not valid.

psalm-suppress

LessSpecificReturnStatement

psalm-suppress

MoreSpecificReturnType

psalm-pure
Return values
static —

The maximum value.

min()

Returns the minimum of the given values.

public static min(BigNumber|int|float|string ...$values) : static
Parameters
$values : BigNumber|int|float|string

The numbers to compare. All the numbers need to be convertible to an instance of the class this method is called on.

Tags
throws
InvalidArgumentException

If no values are given.

throws
MathException

If an argument is not valid.

psalm-suppress

LessSpecificReturnStatement

psalm-suppress

MoreSpecificReturnType

psalm-pure
Return values
static —

The minimum value.

minus()

Returns the difference of this number and the given one.

public minus(BigNumber|int|float|string $that) : BigInteger
Parameters
$that : BigNumber|int|float|string

The number to subtract. Must be convertible to a BigInteger.

Tags
throws
MathException

If the number is not valid, or is not convertible to a BigInteger.

Return values
BigInteger —

The result.

mod()

Returns the modulo of this number and the given one.

public mod(BigNumber|int|float|string $that) : BigInteger

The modulo operation yields the same result as the remainder operation when both operands are of the same sign, and may differ when signs are different.

The result of the modulo operation, when non-zero, has the same sign as the divisor.

Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigInteger.

Tags
throws
DivisionByZeroException

If the divisor is zero.

Return values
BigInteger —

modPow()

Returns this number raised into power with modulo.

public modPow(BigNumber|int|float|string $exp, BigNumber|int|float|string $mod) : BigInteger

This operation only works on positive numbers.

Parameters
$exp : BigNumber|int|float|string

The exponent. Must be positive or zero.

$mod : BigNumber|int|float|string

The modulus. Must be strictly positive.

Tags
throws
NegativeNumberException

If any of the operands is negative.

throws
DivisionByZeroException

If the modulus is zero.

Return values
BigInteger —

multipliedBy()

Returns the product of this number and the given one.

public multipliedBy(BigNumber|int|float|string $that) : BigInteger
Parameters
$that : BigNumber|int|float|string

The multiplier. Must be convertible to a BigInteger.

Tags
throws
MathException

If the multiplier is not a valid number, or is not convertible to a BigInteger.

Return values
BigInteger —

The result.

or()

Returns the integer bitwise-or combined with another integer.

public or(BigNumber|int|float|string $that) : BigInteger

This method returns a negative BigInteger if and only if either of the operands is negative.

Parameters
$that : BigNumber|int|float|string

The operand. Must be convertible to an integer number.

Return values
BigInteger —

plus()

Returns the sum of this number and the given one.

public plus(BigNumber|int|float|string $that) : BigInteger
Parameters
$that : BigNumber|int|float|string

The number to add. Must be convertible to a BigInteger.

Tags
throws
MathException

If the number is not valid, or is not convertible to a BigInteger.

Return values
BigInteger —

The result.

power()

Returns this number exponentiated to the given value.

public power(int $exponent) : BigInteger
Parameters
$exponent : int

The exponent.

Tags
throws
InvalidArgumentException

If the exponent is not in the range 0 to 1,000,000.

Return values
BigInteger —

The result.

quotientAndRemainder()

Returns the quotient and remainder of the division of this number by the given one.

public quotientAndRemainder(BigNumber|int|float|string $that) : array<string|int, BigInteger>
Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigInteger.

Tags
throws
DivisionByZeroException

If the divisor is zero.

Return values
array<string|int, BigInteger> —

An array containing the quotient and the remainder.

randomBits()

Generates a pseudo-random number in the range 0 to 2^numBits - 1.

public static randomBits(int $numBits[, callable|null $randomBytesGenerator = null ]) : BigInteger

Using the default random bytes generator, this method is suitable for cryptographic use.

Parameters
$numBits : int

The number of bits.

$randomBytesGenerator : callable|null = null

A function that accepts a number of bytes as an integer, and returns a string of random bytes of the given length. Defaults to the random_bytes() function.

Tags
psalm-param

callable(int): string $randomBytesGenerator

throws
InvalidArgumentException

If $numBits is negative.

Return values
BigInteger —

randomRange()

Generates a pseudo-random number between `$min` and `$max`.

public static randomRange(BigNumber|int|float|string $min, BigNumber|int|float|string $max[, callable|null $randomBytesGenerator = null ]) : BigInteger

Using the default random bytes generator, this method is suitable for cryptographic use.

Parameters
$min : BigNumber|int|float|string

The lower bound. Must be convertible to a BigInteger.

$max : BigNumber|int|float|string

The upper bound. Must be convertible to a BigInteger.

$randomBytesGenerator : callable|null = null

A function that accepts a number of bytes as an integer, and returns a string of random bytes of the given length. Defaults to the random_bytes() function.

Tags
psalm-param

(callable(int): string)|null $randomBytesGenerator

throws
MathException

If one of the parameters cannot be converted to a BigInteger, or $min is greater than $max.

Return values
BigInteger —

remainder()

Returns the remainder of the division of this number by the given one.

public remainder(BigNumber|int|float|string $that) : BigInteger

The remainder, when non-zero, has the same sign as the dividend.

Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigInteger.

Tags
throws
DivisionByZeroException

If the divisor is zero.

Return values
BigInteger —

shiftedLeft()

Returns the integer left shifted by a given number of bits.

public shiftedLeft(int $distance) : BigInteger
Parameters
$distance : int

The distance to shift.

Return values
BigInteger —

shiftedRight()

Returns the integer right shifted by a given number of bits.

public shiftedRight(int $distance) : BigInteger
Parameters
$distance : int

The distance to shift.

Return values
BigInteger —

sum()

Returns the sum of the given values.

public static sum(BigNumber|int|float|string ...$values) : static
Parameters
$values : BigNumber|int|float|string

The numbers to add. All the numbers need to be convertible to an instance of the class this method is called on.

Tags
throws
InvalidArgumentException

If no values are given.

throws
MathException

If an argument is not valid.

psalm-suppress

LessSpecificReturnStatement

psalm-suppress

MoreSpecificReturnType

psalm-pure
Return values
static —

The sum.

testBit()

Returns true if and only if the designated bit is set.

public testBit(int $n) : bool

Computes ((this & (1<<n)) != 0).

Parameters
$n : int

The bit to test, 0-based.

Tags
throws
InvalidArgumentException

If the bit to test is negative.

Return values
bool —

toArbitraryBase()

Returns a string representation of this number in an arbitrary base with a custom alphabet.

public toArbitraryBase(string $alphabet) : string

Because this method accepts an alphabet with any character, including dash, it does not handle negative numbers; a NegativeNumberException will be thrown when attempting to call this method on a negative number.

Parameters
$alphabet : string

The alphabet, for example '01' for base 2, or '01234567' for base 8.

Tags
throws
NegativeNumberException

If this number is negative.

throws
InvalidArgumentException

If the given alphabet does not contain at least 2 chars.

Return values
string —

toBase()

Returns a string representation of this number in the given base.

public toBase(int $base) : string

The output will always be lowercase for bases greater than 10.

Parameters
$base : int
Tags
throws
InvalidArgumentException

If the base is out of range.

Return values
string —

toBytes()

Returns a string of bytes containing the binary representation of this BigInteger.

public toBytes([bool $signed = true ]) : string

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.

Parameters
$signed : bool = true

Whether to output a signed number in two's-complement representation with a leading sign bit.

Tags
throws
NegativeNumberException

If $signed is false, and the number is negative.

Return values
string —

toFloat()

Returns an approximation of this number as a floating-point value.

public toFloat() : float
Return values
float —

The converted value.

toInt()

Returns the exact value of this number as a native integer.

public toInt() : int
Return values
int —

The converted value.

toScale()

Converts this number to a BigDecimal with the given scale, using rounding if necessary.

public toScale(int $scale[, int $roundingMode = RoundingMode::UNNECESSARY ]) : BigDecimal
Parameters
$scale : int

The scale of the resulting BigDecimal.

$roundingMode : int = RoundingMode::UNNECESSARY

A RoundingMode constant.

Return values
BigDecimal —

xor()

Returns the integer bitwise-xor combined with another integer.

public xor(BigNumber|int|float|string $that) : BigInteger

This method returns a negative BigInteger if and only if exactly one of the operands is negative.

Parameters
$that : BigNumber|int|float|string

The operand. Must be convertible to an integer number.

Return values
BigInteger —

__construct()

Protected constructor. Use a factory method to obtain an instance.

protected __construct(string $value) : mixed
Parameters
$value : string

A string of digits, with optional leading minus sign.

Return values
mixed —

add()

Adds two BigNumber instances in the correct order to avoid a RoundingNecessaryException.

private static add(BigNumber $a, BigNumber $b) : BigNumber
Parameters
$a : BigNumber
$b : BigNumber
Tags
todo

This could be better resolved by creating an abstract protected method in BigNumber, and leaving to concrete classes the responsibility to perform the addition themselves or delegate it to the given number, depending on their ability to perform the operation. This will also require a version bump because we're potentially breaking custom BigNumber implementations (if any...)

psalm-pure
Return values
BigNumber —

cleanUp()

Removes optional leading zeros and + sign from the given number.

private static cleanUp(string $number) : string
Parameters
$number : string

The number, validated as a non-empty string of digits with optional leading sign.

Tags
psalm-pure
Return values
string —

floatToString()

Safely converts float to string, avoiding locale-dependent issues.

private static floatToString(float $float) : string
Parameters
$float : float
Tags
see
https://github.com/brick/math/pull/20
psalm-pure
psalm-suppress

ImpureFunctionCall

Return values
string —

Search results