Value Objects for handling arbitrary precision numbers.
composer require tiny-blocks/math
The library exposes some concrete implementations for arbitrary precision numbers. Concrete implementations implement
the BigNumber
interface, which provides the behaviors for the respective BigNumbers.
With the fromString
method, a new instance of type BigNumber
is created from a valid string numeric value.
BigDecimal::fromString(value: '10');
BigDecimal::fromString(value: '-123.456');
It is possible to set a scale
for the object through this method.
BigDecimal::fromString(value: '10', scale: 2);
Always prefer to instantiate from a string, which supports an unlimited number of digits and ensures no loss of precision.
With the fromFloat
method, a new instance of type BigNumber
is created from a valid float value.
BigDecimal::fromFloat(value: 10.0);
BigDecimal::fromFloat(value: -123.456);
It is also possible to set a scale
for the object through this method.
BigDecimal::fromFloat(value: 10.0, scale: 2);
Performs an addition operation between this value and another value.
$augend = BigDecimal::fromString(value: '1');
$addend = BigDecimal::fromFloat(value: 1.0);
$result = $augend->add(addend: $addend);
$result->toString(); # 2
Performs a subtraction operation between this value and another value.
$minuend = BigDecimal::fromString(value: '1');
$subtrahend = BigDecimal::fromFloat(value: 1.0);
$result = $minuend->subtract(subtrahend: $subtrahend);
$result->toString(); # 0
Performs a multiplication operation between this value and another value.
$multiplicand = BigDecimal::fromString(value: '1');
$multiplier = BigDecimal::fromFloat(value: 1.0);
$result = $multiplicand->multiply(multiplier: $multiplier);
$result->toString(); # 1
Performs a division operation between this value and another value.
$dividend = BigDecimal::fromString(value: '1');
$divisor = BigDecimal::fromFloat(value: 1.0);
$result = $dividend->divide(divisor: $divisor);
$result->toString(); # 1
If you need to perform rounding, you can use the withRounding
method.
Use one of the following constants to specify the mode in which rounding occurs:
-
HALF_UP
: Round number away from zero when halfway.$value = BigDecimal::fromFloat(value: 0.9950, scale: 2); $result = $value->withRounding(mode: RoundingMode::HALF_UP); $result->toString(); # 1
-
HALF_DOWN
: Round number to zero when halfway.$value = BigDecimal::fromFloat(value: 0.9950, scale: 2); $result = $value->withRounding(mode: RoundingMode::HALF_DOWN); $result->toString(); # 0.99
-
HALF_EVEN
: Round number to the nearest even value when halfway.$value = BigDecimal::fromFloat(value: 0.9950, scale: 2); $result = $value->withRounding(mode: RoundingMode::HALF_EVEN); $result->toString(); # 1
-
HALF_ODD
: Round number to the nearest odd value when halfway.$value = BigDecimal::fromFloat(value: 0.9950, scale: 2); $result = $value->withRounding(mode: RoundingMode::HALF_ODD); $result->toString(); # 0.99
Sometimes it is necessary to convert a value to negative, in these cases you can use the negate
method.
$value = BigDecimal::fromFloat(value: 1);
$result = $value->negate();
$result->toString(); # -1
Check out other available resources by looking at the BigNumber interface.
Math is licensed under MIT.
Please follow the contributing guidelines to contribute to the project.