tiny-blocks / math
Value Objects for handling arbitrary precision numbers.
Installs: 8 471
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Requires
- php: ^8.1||^8.2
- ext-bcmath: *
- tiny-blocks/value-object: ^2.0
Requires (Dev)
- infection/infection: ^0.26
- phpmd/phpmd: ^2.13
- phpunit/phpunit: ^9.6
- squizlabs/php_codesniffer: ^3.7
Suggests
- ext-bcmath: Enables the extension which is an interface to the GNU implementation as a Basic Calculator utility library.
README
Overview
Value Objects for handling arbitrary precision numbers.
Installation
composer require tiny-blocks/math
How to use
The library exposes some concrete implementations for arbitrary precision numbers. Concrete implementations implement
the BigNumber
interface, which provides the behaviors for the respective BigNumbers.
Using the from method
With the from
method, a new instance of type BigNumber
is created from a valid numeric value. You can provide
a string
or float
value.
BigDecimal::from(value: '10'); BigDecimal::from(value: 10);
It is possible to set a scale
for the object through the from
method.
BigDecimal::from(value: '10', scale: 2);
Floating point values instantiated from a float
may not be safe, as they are imprecise by design and may result in a
loss of precision. Always prefer to instantiate from a string
, which supports an unlimited amount digits.
Using the methods of mathematical operations
Addition
Performs an addition operation between this value and another value.
$augend = BigDecimal::from(value: 1); $addend = BigDecimal::from(value: '1'); $result = $augend->add(addend: $addend); $result->toString(); # 2
Subtraction
Performs a subtraction operation between this value and another value.
$minuend = BigDecimal::from(value: 1); $subtrahend = BigDecimal::from(value: '1'); $result = $minuend->subtract(subtrahend: $subtrahend); $result->toString(); # 0
Multiplication
Performs a multiplication operation between this value and another value.
$multiplicand = BigDecimal::from(value: 1); $multiplier = BigDecimal::from(value: '1'); $result = $multiplicand->multiply(multiplier: $multiplier); $result->toString(); # 1
Division
Performs a division operation between this value and another value.
$dividend = BigDecimal::from(value: 1); $divisor = BigDecimal::from(value: '1'); $result = $dividend->divide(divisor: $divisor); $result->toString(); # 1
Using other resources
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::from(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::from(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::from(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::from(value: 0.9950, scale: 2); $result = $value->withRounding(mode: RoundingMode::HALF_ODD); $result->toString(); # 0.99
Negate
Sometimes it is necessary to convert a value to negative, in these cases you can use the negate
method.
$value = BigDecimal::from(value: 1); $result = $value->negate(); $result->toString(); # -1
Others
Check out other available resources by looking at the BigNumber interface.
License
Math is licensed under MIT.
Contributing
Please follow the contributing guidelines to contribute to the project.