Documentation

BigDecimal extends BigNumber
in package

Immutable, arbitrary-precision signed decimal numbers.

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.
$scale  : int
The scale (number of digits after the decimal point) of this decimal number.
$value  : string
The unscaled value of this decimal number.
__toString()  : string
Returns a string representation of this number.
abs()  : BigDecimal
Returns the absolute value of this number.
compareTo()  : int
Compares this number to the given one.
dividedBy()  : BigDecimal
Returns the result of the division of this number by the given one, at the given scale.
exactlyDividedBy()  : BigDecimal
Returns the exact result of the division of this number by the given one.
getFractionalPart()  : string
Returns a string representing the fractional part of this decimal number.
getIntegralPart()  : string
Returns a string representing the integral part of this decimal number.
getScale()  : int
getSign()  : int
Returns the sign of this number.
getUnscaledValue()  : BigInteger
hasNonZeroFractionalPart()  : bool
Returns whether this decimal number has a non-zero fractional part.
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.
minus()  : BigDecimal
Returns the difference of this number and the given one.
multipliedBy()  : BigDecimal
Returns the product of this number and the given one.
negated()  : BigDecimal
Returns the negated value of this number.
of()  : BigDecimal
Creates a BigDecimal of the given value.
ofUnscaledValue()  : BigDecimal
Creates a BigDecimal from an unscaled value and a scale.
one()  : BigDecimal
Returns a BigDecimal representing one, with a scale of zero.
plus()  : BigDecimal
Returns the sum of this number and the given one.
power()  : BigDecimal
Returns this number exponentiated to the given value.
quotient()  : BigDecimal
Returns the quotient of the division of this number by this given one.
quotientAndRemainder()  : array<string|int, BigDecimal>
Returns the quotient and remainder of the division of this number by the given one.
remainder()  : BigDecimal
Returns the remainder of the division of this number by this given one.
sqrt()  : BigDecimal
Returns the square root of this number, rounded down to the given number of decimals.
stripTrailingZeros()  : BigDecimal
Returns a copy of this BigDecimal with any trailing zeros removed from the fractional part.
sum()  : static
Returns the sum of the given values.
ten()  : BigDecimal
Returns a BigDecimal representing ten, with a scale of zero.
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.
withPointMovedLeft()  : BigDecimal
Returns a copy of this BigDecimal with the decimal point moved $n places to the left.
withPointMovedRight()  : BigDecimal
Returns a copy of this BigDecimal with the decimal point moved $n places to the right.
zero()  : BigDecimal
Returns a BigDecimal representing zero, with a scale of 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.
getUnscaledValueWithLeadingZeros()  : string
Adds leading zeros if necessary to the unscaled value to represent the full decimal number.
scaleValues()  : array<string|int, mixed>
Puts the internal values of the given decimal numbers on the same scale.
valueWithMinScale()  : string

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

$scale

The scale (number of digits after the decimal point) of this decimal number.

private int $scale

This must be zero or more.

$value

The unscaled value of this decimal number.

private string $value

This is a string of digits with an optional leading minus sign. No leading zero must be present. No leading minus sign must be present if the value is 0.

Methods

__toString()

Returns a string representation of this number.

public __toString() : string
Return values
string —

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, at the given scale.

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

The divisor.

$scale : int|null = null

The desired scale, or null to use the scale of this number.

$roundingMode : int = RoundingMode::UNNECESSARY

An optional rounding mode.

Tags
throws
InvalidArgumentException

If the scale or rounding mode is invalid.

throws
MathException

If the number is invalid, is zero, or rounding was necessary.

Return values
BigDecimal —

exactlyDividedBy()

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

public exactlyDividedBy(BigNumber|int|float|string $that) : BigDecimal

The scale of the result is automatically calculated to fit all the fraction digits.

Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigDecimal.

Tags
throws
MathException

If the divisor is not a valid number, is not convertible to a BigDecimal, is zero, or the result yields an infinite number of digits.

Return values
BigDecimal —

The result.

getFractionalPart()

Returns a string representing the fractional part of this decimal number.

public getFractionalPart() : string

If the scale is zero, an empty string is returned.

Examples: -123.456 => '456', 123 => ''.

Return values
string —

getIntegralPart()

Returns a string representing the integral part of this decimal number.

public getIntegralPart() : string

Example: -123.456 => -123.

Return values
string —

getScale()

public getScale() : int
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.

hasNonZeroFractionalPart()

Returns whether this decimal number has a non-zero fractional part.

public hasNonZeroFractionalPart() : bool
Return values
bool —

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.

minus()

Returns the difference of this number and the given one.

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

The result has a scale of max($this->scale, $that->scale).

Parameters
$that : BigNumber|int|float|string

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

Tags
throws
MathException

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

Return values
BigDecimal —

The result.

multipliedBy()

Returns the product of this number and the given one.

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

The result has a scale of $this->scale + $that->scale.

Parameters
$that : BigNumber|int|float|string

The multiplier. Must be convertible to a BigDecimal.

Tags
throws
MathException

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

Return values
BigDecimal —

The result.

ofUnscaledValue()

Creates a BigDecimal from an unscaled value and a scale.

public static ofUnscaledValue(BigNumber|int|float|string $value[, int $scale = 0 ]) : BigDecimal

Example: (12345, 3) will result in the BigDecimal 12.345.

Parameters
$value : BigNumber|int|float|string

The unscaled value. Must be convertible to a BigInteger.

$scale : int = 0

The scale of the number, positive or zero.

Tags
throws
InvalidArgumentException

If the scale is negative.

psalm-pure
Return values
BigDecimal —

plus()

Returns the sum of this number and the given one.

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

The result has a scale of max($this->scale, $that->scale).

Parameters
$that : BigNumber|int|float|string

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

Tags
throws
MathException

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

Return values
BigDecimal —

The result.

power()

Returns this number exponentiated to the given value.

public power(int $exponent) : BigDecimal

The result has a scale of $this->scale * $exponent.

Parameters
$exponent : int

The exponent.

Tags
throws
InvalidArgumentException

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

Return values
BigDecimal —

The result.

quotient()

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

public quotient(BigNumber|int|float|string $that) : BigDecimal

The quotient has a scale of 0.

Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigDecimal.

Tags
throws
MathException

If the divisor is not a valid decimal number, or is zero.

Return values
BigDecimal —

The quotient.

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, BigDecimal>

The quotient has a scale of 0, and the remainder has a scale of max($this->scale, $that->scale).

Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigDecimal.

Tags
throws
MathException

If the divisor is not a valid decimal number, or is zero.

Return values
array<string|int, BigDecimal> —

An array containing the quotient and the remainder.

remainder()

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

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

The remainder has a scale of max($this->scale, $that->scale).

Parameters
$that : BigNumber|int|float|string

The divisor. Must be convertible to a BigDecimal.

Tags
throws
MathException

If the divisor is not a valid decimal number, or is zero.

Return values
BigDecimal —

The remainder.

sqrt()

Returns the square root of this number, rounded down to the given number of decimals.

public sqrt(int $scale) : BigDecimal
Parameters
$scale : int
Tags
throws
InvalidArgumentException

If the scale is negative.

throws
NegativeNumberException

If this number is negative.

Return values
BigDecimal —

stripTrailingZeros()

Returns a copy of this BigDecimal with any trailing zeros removed from the fractional part.

public stripTrailingZeros() : BigDecimal
Return values
BigDecimal —

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

withPointMovedLeft()

Returns a copy of this BigDecimal with the decimal point moved $n places to the left.

public withPointMovedLeft(int $n) : BigDecimal
Parameters
$n : int
Return values
BigDecimal —

withPointMovedRight()

Returns a copy of this BigDecimal with the decimal point moved $n places to the right.

public withPointMovedRight(int $n) : BigDecimal
Parameters
$n : int
Return values
BigDecimal —

__construct()

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

protected __construct(string $value[, int $scale = 0 ]) : mixed
Parameters
$value : string

The unscaled value, validated.

$scale : int = 0

The scale, validated.

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 —

getUnscaledValueWithLeadingZeros()

Adds leading zeros if necessary to the unscaled value to represent the full decimal number.

private getUnscaledValueWithLeadingZeros() : string
Return values
string —

scaleValues()

Puts the internal values of the given decimal numbers on the same scale.

private scaleValues(BigDecimal $x, BigDecimal $y) : array<string|int, mixed>
Parameters
$x : BigDecimal

The first decimal number.

$y : BigDecimal

The second decimal number.

Return values
array<string|int, mixed> —

valueWithMinScale()

private valueWithMinScale(int $scale) : string
Parameters
$scale : int
Return values
string —

Search results