Documentation

BigNumber
in package
implements Serializable, JsonSerializable

Common interface for arbitrary-precision rational numbers.

Tags
psalm-immutable

Interfaces, Classes, Traits and Enums

Serializable
JsonSerializable

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.
__toString()  : string
Returns a string representation of this number.
compareTo()  : int
Compares this number to the given one.
getSign()  : int
Returns the sign of this number.
isEqualTo()  : bool
Checks if this number is equal to the given one.
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.
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.
of()  : BigNumber
Creates a BigNumber of the given value.
sum()  : static
Returns the sum of the given values.
toBigDecimal()  : BigDecimal
Converts this number to a BigDecimal.
toBigInteger()  : BigInteger
Converts this number to a BigInteger.
toBigRational()  : BigRational
Converts this number to a BigRational.
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.
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]+)' . ')' . ')' . '$/'

Methods

__toString()

Returns a string representation of this number.

public abstract __toString() : string

The output of this method can be parsed by the of() factory method; this will yield an object equal to this one, without any information loss.

Return values
string —

compareTo()

Compares this number to the given one.

public abstract compareTo(BigNumber|int|float|string $that) : int
Parameters
$that : BigNumber|int|float|string
Tags
throws
MathException

If the number is not valid.

Return values
int —

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

getSign()

Returns the sign of this number.

public abstract 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 —

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 —

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.

of()

Creates a BigNumber of the given value.

public static of(BigNumber|int|float|string $value) : BigNumber

The concrete return type is dependent on the given value, with the following rules:

  • BigNumber instances are returned as is
  • integer numbers are returned as BigInteger
  • floating point numbers are converted to a string then parsed as such
  • strings containing a / character are returned as BigRational
  • strings containing a . character or using an exponential notation are returned as BigDecimal
  • strings containing only digits with an optional leading + or - sign are returned as BigInteger
Parameters
$value : BigNumber|int|float|string
Tags
throws
NumberFormatException

If the format of the number is not valid.

throws
DivisionByZeroException

If the value represents a rational number with a denominator of zero.

psalm-pure
Return values
BigNumber —

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.

toFloat()

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

public abstract toFloat() : float

Note that this method can discard information as the precision of a floating-point value is inherently limited.

If the number is greater than the largest representable floating point number, positive infinity is returned. If the number is less than the smallest representable floating point number, negative infinity is returned.

Return values
float —

The converted value.

toInt()

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

public abstract toInt() : int

If this number cannot be converted to a native integer without losing precision, an exception is thrown. Note that the acceptable range for an integer depends on the platform and differs for 32-bit and 64-bit.

Tags
throws
MathException

If this number cannot be exactly converted to a native integer.

Return values
int —

The converted value.

toScale()

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

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

The scale of the resulting BigDecimal.

$roundingMode : int = RoundingMode::UNNECESSARY

A RoundingMode constant.

Tags
throws
RoundingNecessaryException

If this number cannot be converted to the given scale without rounding. This only applies when RoundingMode::UNNECESSARY is used.

Return values
BigDecimal —

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