mirror of
https://github.com/danog/math.git
synced 2024-11-27 12:24:45 +01:00
121 lines
5.6 KiB
Markdown
121 lines
5.6 KiB
Markdown
Brick\Math
|
|
==========
|
|
|
|
Provides the `BigInteger` and `BigDecimal` classes to work with arbitrary precision numbers.
|
|
|
|
[](http://travis-ci.org/brick/math)
|
|
[](https://coveralls.io/r/brick/math?branch=master)
|
|
|
|
Installation
|
|
------------
|
|
|
|
This library is installable via [Composer](https://getcomposer.org/).
|
|
Just define the following requirement in your `composer.json` file:
|
|
|
|
{
|
|
"require": {
|
|
"brick/math": "*"
|
|
}
|
|
}
|
|
|
|
Requirements
|
|
------------
|
|
|
|
This library requires PHP 5.6, PHP 7 or [HHVM](http://hhvm.com/).
|
|
|
|
Although the library can work on any PHP installation, it is highly recommended that you install the
|
|
[GMP](http://php.net/manual/en/book.gmp.php) or [BCMath](http://php.net/manual/en/book.bc.php) extension
|
|
to speed up calculations. The fastest available calculator implementation will be automatically selected at runtime.
|
|
|
|
Package contents
|
|
----------------
|
|
|
|
This library provides the following public classes:
|
|
|
|
- `Brick\Math\ArithmeticException`: exception thrown when an error occurs.
|
|
- `Brick\Math\BigInteger`: represents an arbitrary-precision integer number.
|
|
- `Brick\Math\BigDecimal`: represents an arbitrary-precision decimal number.
|
|
- `Brick\Math\RoundingMode`: holds constants for the [rounding modes](#division--rounding-modes).
|
|
|
|
Overview
|
|
--------
|
|
|
|
### Instantiation
|
|
|
|
The constructor of `BigInteger` and `BigDecimal` is private,
|
|
you must use the `of()` factory method to obtain an instance:
|
|
|
|
$integer = BigInteger::of('123456');
|
|
$decimal = BigDecimal::of('123.456');
|
|
|
|
The following types are accepted: `integer`, `float`, `string` as long as they can be safely converted to an integer
|
|
in the case of `BigInteger::of()`, or to a decimal number in the case of `BigDecimal::of()`.
|
|
|
|
Prefer instantiating from `string` or `integer` rather than `float`, as floating-point values are imprecise by design,
|
|
and using them with `of()` defeats the purpose of using an arbitrary precision library.
|
|
|
|
Only `string` allows you to safely instantiate a number with an unlimited number of digits.
|
|
|
|
### Immutability
|
|
|
|
The `BigInteger` and `BigDecimal` classes are immutable: their value never changes, so that they can be safely passed around. All methods that return a `BigInteger` or `BigDecimal` return a new object, leaving the original object unaffected:
|
|
|
|
$ten = BigInteger::of(10);
|
|
|
|
echo $ten->plus(5); // 15
|
|
echo $ten->multipliedBy(3); // 30
|
|
|
|
### Parameter types
|
|
|
|
All methods that accept a number: `plus()`, `minus()`, `multipliedBy()`, etc. accept the same types as `of()`.
|
|
As an example, given the following number:
|
|
|
|
$integer = BigInteger::of(123);
|
|
|
|
The following lines are equivalent:
|
|
|
|
$integer->multipliedBy(123);
|
|
$integer->multipliedBy('123');
|
|
$integer->multipliedBy($integer);
|
|
|
|
### Chaining
|
|
|
|
All the methods that return a new number can be chained, for example:
|
|
|
|
echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 45
|
|
|
|
### Division & rounding modes
|
|
|
|
When dividing numbers, if the remainder of the division if not zero, the result needs to be rounded up or down. By default, the library assumes that rounding is unnecessary, and throws an exception if the remainder of the division is not zero:
|
|
|
|
BigInteger::of(7)->dividedBy(2); // throws an ArithmeticException
|
|
|
|
In that case, you need to explicitly provide a rounding mode:
|
|
|
|
echo BigInteger::of(7)->dividedBy(2, RoundingMode::DOWN); // 3
|
|
echo BigInteger::of(7)->dividedBy(2, RoundingMode::UP); // 4
|
|
|
|
When dividing a `BigDecimal`, you can also specify the scale of the result:
|
|
|
|
echo BigDecimal::of(3)->dividedBy(11, 2, RoundingMode::UP); // 0.28
|
|
echo BigDecimal::of(3)->dividedBy(11, 6, RoundingMode::DOWN); // 0.272727
|
|
|
|
There are a number of rounding modes you can use:
|
|
|
|
Rounding mode | Description
|
|
-------------- | -----------
|
|
`UNNECESSARY` | Assumes that no rounding is necessary, and throws an exception if it is.
|
|
`UP` | Rounds away from zero.
|
|
`DOWN` | Rounds towards zero.
|
|
`CEILING` | Rounds towards positive infinity. If the result is positive, behaves as for `UP`; if negative, behaves as for `DOWN`.
|
|
`FLOOR` | Rounds towards negative infinity. If the result is positive, behave as for `DOWN`; if negative, behave as for `UP`.
|
|
`HALF_UP` | Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round up. Behaves as for `UP` if the discarded fraction is >= 0.5; otherwise, behaves as for `DOWN`.
|
|
`HALF_DOWN` | Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round down. Behaves as for `UP` if the discarded fraction is > 0.5; otherwise, behaves as for `DOWN`.
|
|
`HALF_CEILING` | Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards positive infinity. If the result is positive, behaves as for `HALF_UP`; if negative, behaves as for `HALF_DOWN`.
|
|
`HALF_FLOOR` | Rounds towards "nearest neighbor" unless both neighbors are equidistant, in which case round towards negative infinity. If the result is positive, behaves as for `HALF_DOWN`; if negative, behaves as for `HALF_UP`.
|
|
`HALF_EVEN` | Rounds towards the "nearest neighbor" unless both neighbors are equidistant, in which case rounds towards the even neighbor. Behaves as for `HALF_UP` if the digit to the left of the discarded fraction is odd; behaves as for `HALF_DOWN` if it's even.
|
|
|
|
### Serialization
|
|
|
|
`BigInteger` and `BigDecimal` can be safely serialized on a machine and unserialized on another.
|
|
No context is stored in the serialized variable, only the value. |