264 lines
9.3 KiB
Markdown
264 lines
9.3 KiB
Markdown
## Brick\Math
|
|
|
|
<img src="https://raw.githubusercontent.com/brick/brick/master/logo.png" alt="" align="left" height="64">
|
|
|
|
A PHP library to work with arbitrary precision numbers.
|
|
|
|
[](https://github.com/brick/math/actions)
|
|
[](https://codecov.io/github/brick/math)
|
|
[](https://packagist.org/packages/brick/math)
|
|
[](https://packagist.org/packages/brick/math)
|
|
[](http://opensource.org/licenses/MIT)
|
|
|
|
### Installation
|
|
|
|
This library is installable via [Composer](https://getcomposer.org/):
|
|
|
|
```bash
|
|
composer require brick/math
|
|
```
|
|
|
|
### Requirements
|
|
|
|
This library requires PHP 8.2 or later.
|
|
|
|
For PHP 8.1 compatibility, you can use version `0.13`. For PHP 8.0, you can use version `0.11`. For PHP 7.4, you can use version `0.10`. For PHP 7.1, 7.2 & 7.3, you can use version `0.9`. Note that [PHP versions < 8.1 are EOL](http://php.net/supported-versions.php) and not supported anymore. If you're still using one of these PHP versions, you should consider upgrading as soon as possible.
|
|
|
|
Although the library can work seamlessly 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.
|
|
|
|
### Project status & release process
|
|
|
|
While this library is still under development, it is well tested and considered stable enough to use in production
|
|
environments.
|
|
|
|
The current releases are numbered `0.x.y`. When a non-breaking change is introduced (adding new methods, optimizing
|
|
existing code, etc.), `y` is incremented.
|
|
|
|
**When a breaking change is introduced, a new `0.x` version cycle is always started.**
|
|
|
|
It is therefore safe to lock your project to a given release cycle, such as `^0.17`.
|
|
|
|
If you need to upgrade to a newer release cycle, check the [release history](https://github.com/brick/math/releases)
|
|
for a list of changes introduced by each further `0.x.0` version.
|
|
|
|
### Package contents
|
|
|
|
This library provides the following public classes in the `Brick\Math` namespace:
|
|
|
|
- [BigNumber](https://github.com/brick/math/blob/0.17.1/src/BigNumber.php): base class for `BigInteger`, `BigDecimal` and `BigRational`
|
|
- [BigInteger](https://github.com/brick/math/blob/0.17.1/src/BigInteger.php): represents an arbitrary-precision integer number.
|
|
- [BigDecimal](https://github.com/brick/math/blob/0.17.1/src/BigDecimal.php): represents an arbitrary-precision decimal number.
|
|
- [BigRational](https://github.com/brick/math/blob/0.17.1/src/BigRational.php): represents an arbitrary-precision rational number (fraction), always reduced to lowest terms.
|
|
- [RoundingMode](https://github.com/brick/math/blob/0.17.1/src/RoundingMode.php): enum representing all available rounding modes.
|
|
|
|
And [exceptions](#exceptions) in the `Brick\Math\Exception` namespace.
|
|
|
|
### Overview
|
|
|
|
#### Instantiation
|
|
|
|
The constructors of the classes are not public, you must use a factory method to obtain an instance.
|
|
|
|
All classes provide an `of()` factory method that accepts any of the following types:
|
|
|
|
- `BigNumber` instances
|
|
- `int` numbers
|
|
- `string` representations of integer, decimal and rational numbers
|
|
|
|
Example:
|
|
|
|
```php
|
|
BigInteger::of(123546);
|
|
BigInteger::of('9999999999999999999999999999999999999999999');
|
|
|
|
BigDecimal::of('9.99999999999999999999999999999999999999999999');
|
|
|
|
BigRational::of('2/3');
|
|
```
|
|
|
|
Note that all `of()` methods accept all the representations above, *as long as it can be safely converted to
|
|
the current type*:
|
|
|
|
```php
|
|
BigInteger::of('1.00'); // 1
|
|
BigInteger::of('1.01'); // RoundingNecessaryException
|
|
|
|
BigDecimal::of('1/8'); // 0.125
|
|
BigDecimal::of('1/3'); // RoundingNecessaryException
|
|
|
|
BigRational::of('1.1'); // 11/10
|
|
BigRational::of('1.15'); // 23/20 (reduced to lowest terms)
|
|
```
|
|
|
|
> [!NOTE]
|
|
> The `of()` factory method does not accept `float` values, because casting a float to string can be lossy.
|
|
> To convert a float to a `BigDecimal`, use one of the dedicated methods:
|
|
>
|
|
> ```php
|
|
> // Exact IEEE-754 representation — the value the float actually holds:
|
|
> BigDecimal::fromFloatExact(0.1); // 0.1000000000000000055511151231257827021181583404541015625
|
|
>
|
|
> // Shortest decimal that round-trips back to the same float:
|
|
> BigDecimal::fromFloatShortest(0.1); // 0.1
|
|
> ```
|
|
|
|
#### Immutability & chaining
|
|
|
|
The `BigInteger`, `BigDecimal` and `BigRational` classes are immutable: their value never changes,
|
|
so that they can be safely passed around. All methods that return a `BigInteger`, `BigDecimal` or `BigRational`
|
|
return a new object, leaving the original object unaffected:
|
|
|
|
```php
|
|
$ten = BigInteger::of(10);
|
|
|
|
echo $ten->plus(5); // 15
|
|
echo $ten->multipliedBy(3); // 30
|
|
```
|
|
|
|
The methods can be chained for better readability:
|
|
|
|
```php
|
|
echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 45
|
|
```
|
|
|
|
#### Parameter types
|
|
|
|
All methods that accept a number: `plus()`, `minus()`, `multipliedBy()`, etc. accept the same types as `of()`.
|
|
For example, given the following number:
|
|
|
|
```php
|
|
$integer = BigInteger::of(123);
|
|
```
|
|
|
|
The following lines are equivalent:
|
|
|
|
```php
|
|
$integer->multipliedBy(123);
|
|
$integer->multipliedBy('123');
|
|
$integer->multipliedBy($integer);
|
|
```
|
|
|
|
Just like `of()`, other types of `BigNumber` are acceptable, as long as they can be safely converted to the current type:
|
|
|
|
```php
|
|
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.0')); // 4
|
|
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5')); // RoundingNecessaryException
|
|
echo BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2)); // 5.0
|
|
```
|
|
|
|
#### Division & rounding
|
|
|
|
##### BigInteger
|
|
|
|
By default, dividing a `BigInteger` returns the exact result of the division, or throws an exception if the remainder
|
|
of the division is not zero:
|
|
|
|
```php
|
|
echo BigInteger::of(999)->dividedBy(3); // 333
|
|
echo BigInteger::of(1000)->dividedBy(3); // RoundingNecessaryException
|
|
```
|
|
|
|
You can pass an optional [rounding mode](https://github.com/brick/math/blob/0.17.1/src/RoundingMode.php) to round the result, if necessary:
|
|
|
|
```php
|
|
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::Down); // 333
|
|
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::Up); // 334
|
|
```
|
|
|
|
If you're into quotients and remainders, there are methods for this, too:
|
|
|
|
```php
|
|
echo BigInteger::of(1000)->quotient(3); // 333
|
|
echo BigInteger::of(1000)->remainder(3); // 1
|
|
```
|
|
|
|
You can even get both at the same time:
|
|
|
|
```php
|
|
[$quotient, $remainder] = BigInteger::of(1000)->quotientAndRemainder(3);
|
|
```
|
|
|
|
##### BigDecimal
|
|
|
|
Dividing a `BigDecimal` always requires a scale to be specified. If the exact result of the division does not fit in
|
|
the given scale, a [rounding mode](https://github.com/brick/math/blob/0.17.1/src/RoundingMode.php) must be provided.
|
|
|
|
```php
|
|
echo BigDecimal::of(1)->dividedBy('8', 3); // 0.125
|
|
echo BigDecimal::of(1)->dividedBy('8', 2); // RoundingNecessaryException
|
|
echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HalfDown); // 0.12
|
|
echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HalfUp); // 0.13
|
|
```
|
|
|
|
If you know that the division yields a finite number of decimals places, you can use `dividedByExact()`, which will
|
|
automatically compute the required scale to fit the result, or throw an exception if the division yields an infinite
|
|
repeating decimal:
|
|
|
|
```php
|
|
echo BigDecimal::of(1)->dividedByExact(256); // 0.00390625
|
|
echo BigDecimal::of(1)->dividedByExact(11); // RoundingNecessaryException
|
|
```
|
|
|
|
##### BigRational
|
|
|
|
The result of the division of a `BigRational` can always be represented exactly:
|
|
|
|
```php
|
|
echo BigRational::of('13/99')->dividedBy('7'); // 13/693
|
|
echo BigRational::of('13/99')->dividedBy('9/8'); // 104/891
|
|
```
|
|
|
|
#### Bitwise operations
|
|
|
|
`BigInteger` supports bitwise operations:
|
|
|
|
- `and()`
|
|
- `or()`
|
|
- `xor()`
|
|
- `not()`
|
|
|
|
and bit shifting:
|
|
|
|
- `shiftedLeft()`
|
|
- `shiftedRight()`
|
|
|
|
#### Exceptions
|
|
|
|
All exceptions thrown by this library implement the `MathException` interface.
|
|
This means that you can safely catch all exceptions thrown by this library using a single catch clause:
|
|
|
|
```php
|
|
use Brick\Math\BigDecimal;
|
|
use Brick\Math\Exception\MathException;
|
|
|
|
try {
|
|
$number = BigInteger::of(1)->dividedBy(3);
|
|
} catch (MathException $e) {
|
|
// ...
|
|
}
|
|
```
|
|
|
|
If you need more granular control over the exceptions thrown, you can catch the specific exception classes:
|
|
|
|
- `DivisionByZeroException`
|
|
- `IntegerOverflowException`
|
|
- `InvalidArgumentException`
|
|
- `NegativeNumberException`
|
|
- `NoInverseException`
|
|
- `NumberFormatException`
|
|
- `RoundingNecessaryException`
|
|
|
|
#### Serialization
|
|
|
|
`BigInteger`, `BigDecimal` and `BigRational` can be safely serialized on a machine and unserialized on another,
|
|
even if these machines do not share the same set of PHP extensions.
|
|
|
|
For example, serializing on a machine with GMP support and unserializing on a machine that does not have this extension
|
|
installed will still work as expected.
|
|
|
|
#### PHPStan extension
|
|
|
|
A third-party [PHPStan extension](https://github.com/simPod/phpstan-brick-math) is available for this library. It provides more specific throw type narrowing for brick/math methods, so that PHPStan can infer the exact exception classes thrown. Note that this extension is not maintained by the author of brick/math.
|