BigDecimal

Immutable, arbitrary-precision signed decimal numbers.

Full name: \Brick\Math\BigDecimal
Parent class: \Brick\Math\BigNumber
This class is marked as final and can't be subclassed
This class is a Final class

Properties

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.

scale

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

private int $scale

This must be zero or more.

Methods

__construct

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

protected __construct(string $value, int $scale): mixed

Parameters:

Parameter	Type	Description
`$value`	string	The unscaled value, validated.
`$scale`	int	The scale, validated.

of

Creates a BigDecimal of the given value.

public static of(\Brick\Math\BigNumber|int|float|string $value): \Brick\Math\BigDecimal

This method is static.

Parameters:

Parameter	Type	Description
`$value`	\Brick\Math\BigNumber\|int\|float\|string

Throws:

If the value cannot be converted to a BigDecimal.

MathException

ofUnscaledValue

Creates a BigDecimal from an unscaled value and a scale.

public static ofUnscaledValue(\Brick\Math\BigNumber|int|float|string $value, int $scale): \Brick\Math\BigDecimal

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

This method is static.

Parameters:

Parameter	Type	Description
`$value`	\Brick\Math\BigNumber\|int\|float\|string	The unscaled value. Must be convertible to a BigInteger.
`$scale`	int	The scale of the number, positive or zero.

Throws:

If the scale is negative.

InvalidArgumentException

zero

Returns a BigDecimal representing zero, with a scale of zero.

public static zero(): \Brick\Math\BigDecimal

This method is static.

one

Returns a BigDecimal representing one, with a scale of zero.

public static one(): \Brick\Math\BigDecimal

This method is static.

ten

Returns a BigDecimal representing ten, with a scale of zero.

public static ten(): \Brick\Math\BigDecimal

This method is static.

plus

Returns the sum of this number and the given one.

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

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

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The number to add. Must be convertible to a BigDecimal.

Throws:

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

MathException

minus

Returns the difference of this number and the given one.

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

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

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The number to subtract. Must be convertible to a BigDecimal.

Throws:

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

MathException

multipliedBy

Returns the product of this number and the given one.

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

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

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The multiplier. Must be convertible to a BigDecimal.

Throws:

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

MathException

dividedBy

Returns the result of the division of this number by the given one, at the given scale.

public dividedBy(\Brick\Math\BigNumber|int|float|string $that, int|null $scale = null, int $roundingMode = RoundingMode::UNNECESSARY): \Brick\Math\BigDecimal

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The divisor.
`$scale`	int\|null	The desired scale, or null to use the scale of this number.
`$roundingMode`	int	An optional rounding mode.

Throws:

If the scale or rounding mode is invalid.

InvalidArgumentException

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

MathException

exactlyDividedBy

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

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

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

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The divisor. Must be convertible to a BigDecimal.

Throws:

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.

MathException

power

Returns this number exponentiated to the given value.

public power(int $exponent): \Brick\Math\BigDecimal

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

Parameters:

Parameter	Type	Description
`$exponent`	int

Throws:

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

InvalidArgumentException

quotient

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

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

The quotient has a scale of 0.

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The divisor. Must be convertible to a BigDecimal.

Throws:

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

MathException

remainder

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

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

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

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The divisor. Must be convertible to a BigDecimal.

Throws:

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

MathException

quotientAndRemainder

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

public quotientAndRemainder(\Brick\Math\BigNumber|int|float|string $that): \Brick\Math\BigDecimal[]

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

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string	The divisor. Must be convertible to a BigDecimal.

Return Value:

An array containing the quotient and the remainder.

Throws:

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

MathException

sqrt

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

public sqrt(int $scale): \Brick\Math\BigDecimal

Parameters:

Parameter	Type	Description
`$scale`	int

Throws:

If the scale is negative.

InvalidArgumentException

If this number is negative.

NegativeNumberException

withPointMovedLeft

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

public withPointMovedLeft(int $n): \Brick\Math\BigDecimal

Parameters:

Parameter	Type	Description
`$n`	int

withPointMovedRight

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

public withPointMovedRight(int $n): \Brick\Math\BigDecimal

Parameters:

Parameter	Type	Description
`$n`	int

stripTrailingZeros

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

public stripTrailingZeros(): \Brick\Math\BigDecimal

abs

Returns the absolute value of this number.

public abs(): \Brick\Math\BigDecimal

negated

Returns the negated value of this number.

public negated(): \Brick\Math\BigDecimal

compareTo

Compares this number to the given one.

public compareTo(\Brick\Math\BigNumber|int|float|string $that): int

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

Return Value:

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

getSign

Returns the sign of this number.

public getSign(): int

Return Value:

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

getUnscaledValue

public getUnscaledValue(): \Brick\Math\BigInteger

getScale

public getScale(): int

getIntegralPart

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

public getIntegralPart(): string

Example: -123.456 => -123.

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 => ''.

hasNonZeroFractionalPart

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

public hasNonZeroFractionalPart(): bool

toBigInteger

Converts this number to a BigInteger.

public toBigInteger(): \Brick\Math\BigInteger

toBigDecimal

Converts this number to a BigDecimal.

public toBigDecimal(): \Brick\Math\BigDecimal

toBigRational

Converts this number to a BigRational.

public toBigRational(): \Brick\Math\BigRational

toScale

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

public toScale(int $scale, int $roundingMode = RoundingMode::UNNECESSARY): \Brick\Math\BigDecimal

Parameters:

Parameter	Type	Description
`$scale`	int	The scale of the resulting `BigDecimal`.
`$roundingMode`	int	A `RoundingMode` constant.

toInt

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

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

toFloat

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

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

__toString

Returns a string representation of this number.

public __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.

scaleValues

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

private scaleValues(\Brick\Math\BigDecimal $x, \Brick\Math\BigDecimal $y): array{: string, : string}

Parameters:

Parameter	Type	Description
`$x`	\Brick\Math\BigDecimal
`$y`	\Brick\Math\BigDecimal

Return Value:

The scaled integer values of $x and $y.

valueWithMinScale

private valueWithMinScale(int $scale): string

Parameters:

Parameter	Type	Description
`$scale`	int

getUnscaledValueWithLeadingZeros

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

private getUnscaledValueWithLeadingZeros(): string

Inherited methods

of

Creates a BigNumber of the given value.

public static of(\Brick\Math\BigNumber|int|float|string $value): \Brick\Math\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
This method is static.

Parameters:

Parameter	Type	Description
`$value`	\Brick\Math\BigNumber\|int\|float\|string

Throws:

If the format of the number is not valid.

NumberFormatException

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

DivisionByZeroException

floatToString

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

private static floatToString(float $float): string

This method is static.

Parameters:

Parameter	Type	Description
`$float`	float

See Also:

https://github.com/brick/math/pull/20 -

min

Returns the minimum of the given values.

public static min(\Brick\Math\BigNumber|int|float|string $values): static

This method is static.

Parameters:

Parameter	Type	Description
`$values`	\Brick\Math\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.

Throws:

If no values are given.

InvalidArgumentException

If an argument is not valid.

MathException

max

Returns the maximum of the given values.

public static max(\Brick\Math\BigNumber|int|float|string $values): static

This method is static.

Parameters:

Parameter	Type	Description
`$values`	\Brick\Math\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.

Throws:

If no values are given.

InvalidArgumentException

If an argument is not valid.

MathException

sum

Returns the sum of the given values.

public static sum(\Brick\Math\BigNumber|int|float|string $values): static

This method is static.

Parameters:

Parameter	Type	Description
`$values`	\Brick\Math\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.

Throws:

If no values are given.

InvalidArgumentException

If an argument is not valid.

MathException

add

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

private static add(\Brick\Math\BigNumber $a, \Brick\Math\BigNumber $b): \Brick\Math\BigNumber

This method is static.

Parameters:

Parameter	Type	Description
`$a`	\Brick\Math\BigNumber
`$b`	\Brick\Math\BigNumber

cleanUp

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

private static cleanUp(string $number): string

This method is static.

Parameters:

Parameter	Type	Description
`$number`	string	The number, validated as a non-empty string of digits with optional leading sign.

isEqualTo

Checks if this number is equal to the given one.

public isEqualTo(\Brick\Math\BigNumber|int|float|string $that): bool

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

isLessThan

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

public isLessThan(\Brick\Math\BigNumber|int|float|string $that): bool

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

isLessThanOrEqualTo

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

public isLessThanOrEqualTo(\Brick\Math\BigNumber|int|float|string $that): bool

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

isGreaterThan

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

public isGreaterThan(\Brick\Math\BigNumber|int|float|string $that): bool

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

isGreaterThanOrEqualTo

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

public isGreaterThanOrEqualTo(\Brick\Math\BigNumber|int|float|string $that): bool

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

isZero

Checks if this number equals zero.

public isZero(): bool

isNegative

Checks if this number is strictly negative.

public isNegative(): bool

isNegativeOrZero

Checks if this number is negative or zero.

public isNegativeOrZero(): bool

isPositive

Checks if this number is strictly positive.

public isPositive(): bool

isPositiveOrZero

Checks if this number is positive or zero.

public isPositiveOrZero(): bool

getSign

Returns the sign of this number.

public getSign(): int

This method is abstract.

Return Value:

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

compareTo

Compares this number to the given one.

public compareTo(\Brick\Math\BigNumber|int|float|string $that): int

This method is abstract.

Parameters:

Parameter	Type	Description
`$that`	\Brick\Math\BigNumber\|int\|float\|string

Return Value:

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

Throws:

If the number is not valid.

MathException

toBigInteger

Converts this number to a BigInteger.

public toBigInteger(): \Brick\Math\BigInteger

This method is abstract.

Throws:

If this number cannot be converted to a BigInteger without rounding.

RoundingNecessaryException

toBigDecimal

Converts this number to a BigDecimal.

public toBigDecimal(): \Brick\Math\BigDecimal

This method is abstract.

Throws:

If this number cannot be converted to a BigDecimal without rounding.

RoundingNecessaryException

toBigRational

Converts this number to a BigRational.

public toBigRational(): \Brick\Math\BigRational

This method is abstract.

toScale

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

public toScale(int $scale, int $roundingMode = RoundingMode::UNNECESSARY): \Brick\Math\BigDecimal

This method is abstract.

Parameters:

Parameter	Type	Description
`$scale`	int	The scale of the resulting `BigDecimal`.
`$roundingMode`	int	A `RoundingMode` constant.

Throws:

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

RoundingNecessaryException

toInt

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

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

This method is abstract.

Throws:

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

MathException

toFloat

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

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

This method is abstract.

__toString

Returns a string representation of this number.

public __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.

This method is abstract.

jsonSerialize

public jsonSerialize(): string

Automatically generated on 2025-03-18