BigDecimal
extends BigNumber
in package
Immutable, arbitrary-precision signed decimal numbers.
Tags
Table of Contents
- PARSE_REGEXP = '/^' . '(?<integral>[\\-\\+]?[0-9]+)' . '(?:' . '(?:' . '(?:\\.(?<fractional>[0-9]+))?' . '(?:[eE](?<exponent>[\\-\\+]?[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
string
PARSE_REGEXP
= '/^' . '(?<integral>[\\-\\+]?[0-9]+)' . '(?:' . '(?:' . '(?:\\.(?<fractional>[0-9]+))?' . '(?:[eE](?<exponent>[\\-\\+]?[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 —abs()
Returns the absolute value of this number.
public
abs() : BigDecimal
Return values
BigDecimal —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
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
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.
getUnscaledValue()
public
getUnscaledValue() : BigInteger
Return values
BigInteger —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
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
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
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
Return values
BigDecimal —The result.
negated()
Returns the negated value of this number.
public
negated() : BigDecimal
Return values
BigDecimal —of()
Creates a BigDecimal of the given value.
public
static of(BigNumber|int|float|string $value) : BigDecimal
Parameters
- $value : BigNumber|int|float|string
Tags
Return values
BigDecimal —ofUnscaledValue()
Creates a BigDecimal from an unscaled value and a scale.
public
static ofUnscaledValue(BigNumber|int|float|string $value, int $scale) : 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
-
The scale of the number, positive or zero.
Tags
Return values
BigDecimal —one()
Returns a BigDecimal representing one, with a scale of zero.
public
static one() : BigDecimal
Tags
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
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
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
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
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
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
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
Return values
static —The sum.
ten()
Returns a BigDecimal representing ten, with a scale of zero.
public
static ten() : BigDecimal
Tags
Return values
BigDecimal —toBigDecimal()
Converts this number to a BigDecimal.
public
toBigDecimal() : BigDecimal
Return values
BigDecimal —The converted number.
toBigInteger()
Converts this number to a BigInteger.
public
toBigInteger() : BigInteger
Return values
BigInteger —The converted number.
toBigRational()
Converts this number to a BigRational.
public
toBigRational() : BigRational
Return values
BigRational —The converted number.
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 —zero()
Returns a BigDecimal representing zero, with a scale of zero.
public
static zero() : BigDecimal
Tags
Return values
BigDecimal —__construct()
Protected constructor. Use a factory method to obtain an instance.
protected
__construct(string $value, int $scale) : mixed
Parameters
- $value : string
-
The unscaled value, validated.
- $scale : int
-
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
Tags
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 sign.
Tags
Return values
string —floatToString()
Safely converts float to string, avoiding locale-dependent issues.
private
static floatToString(float $float) : string
Parameters
- $float : float
Tags
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