mirror of
https://github.com/danog/math.git
synced 2024-11-26 20:04:46 +01:00
Improve README
[ci skip]
This commit is contained in:
Benjamin Morel
parent
70f66fc7c9
commit
d3262776f3
158
README.md
158
README.md
@ -1,5 +1,6 @@
|
||||
Brick\Math
|
||||
==========
|
||||
## Brick\Math
|
||||
|
||||
<img src="https://raw.githubusercontent.com/brick/brick/master/logo.png" alt="" align="left" height="64">
|
||||
|
||||
A library to work with arbitrary precision numbers.
|
||||
|
||||
@ -10,20 +11,20 @@ A library to work with arbitrary precision numbers.
|
||||
|
||||
For a complete list of classes and methods, check the [API documentation](http://brick.io/math/).
|
||||
|
||||
Installation
|
||||
------------
|
||||
### Installation
|
||||
|
||||
This library is installable via [Composer](https://getcomposer.org/).
|
||||
Just define the following requirement in your `composer.json` file:
|
||||
|
||||
{
|
||||
"require": {
|
||||
"brick/math": "0.5.*"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"require": {
|
||||
"brick/math": "0.5.*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Requirements
|
||||
------------
|
||||
### Requirements
|
||||
|
||||
This library requires PHP 5.6, PHP 7 or [HHVM](http://hhvm.com/).
|
||||
|
||||
@ -31,8 +32,7 @@ Although the library can work seamlessly on any PHP installation, it is highly r
|
||||
[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
|
||||
--------------------------------
|
||||
### Project status & release process
|
||||
|
||||
While this library is still under development, it is well tested and should be stable enough to use in production
|
||||
environments.
|
||||
@ -49,8 +49,7 @@ If you want to use the latest version, and receive any non-breaking update, use
|
||||
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
|
||||
----------------
|
||||
### Package contents
|
||||
|
||||
This library provides the following public classes in the [Brick\Math](http://brick.io/math/namespace-Brick.Math.html) namespace:
|
||||
|
||||
@ -67,10 +66,9 @@ And the following exceptions in the [Brick\Math\Exception](http://brick.io/math/
|
||||
- [NumberFormatException](http://brick.io/math/class-Brick.Math.Exception.NumberFormatException.html): thrown when parsing a number string in an invalid format
|
||||
- [RoundingNecessaryException](http://brick.io/math/class-Brick.Math.Exception.RoundingNecessaryException.html): thrown when the result of the operation cannot be represented without explicit rounding
|
||||
|
||||
Overview
|
||||
--------
|
||||
### Overview
|
||||
|
||||
### Instantiation
|
||||
#### Instantiation
|
||||
|
||||
The constructors of the classes are not public, you must use a factory method to obtain an instance.
|
||||
|
||||
@ -83,122 +81,154 @@ All classes provide an `of()` factory method that accepts any of the following t
|
||||
|
||||
Example:
|
||||
|
||||
BigInteger::of(123546);
|
||||
BigInteger::of('9999999999999999999999999999999999999999999');
|
||||
```php
|
||||
BigInteger::of(123546);
|
||||
BigInteger::of('9999999999999999999999999999999999999999999');
|
||||
|
||||
BigDecimal::of(1.2);
|
||||
BigDecimal::of('9.99999999999999999999999999999999999999999999');
|
||||
BigDecimal::of(1.2);
|
||||
BigDecimal::of('9.99999999999999999999999999999999999999999999');
|
||||
|
||||
BigRational::of('2/3');
|
||||
BigRational::of('1.1'); // 11/10
|
||||
BigRational::of('2/3');
|
||||
BigRational::of('1.1'); // 11/10
|
||||
```
|
||||
|
||||
Note that all `of()` methods accept all of the representations above, *as long as it can be safely converted to
|
||||
the current type*:
|
||||
|
||||
BigInteger::of('1.00'); // 1
|
||||
BigInteger::of('1.01'); // ArithmeticException
|
||||
```php
|
||||
BigInteger::of('1.00'); // 1
|
||||
BigInteger::of('1.01'); // ArithmeticException
|
||||
|
||||
BigDecimal::of('1/8'); // 0.125
|
||||
BigDecimal::of('1/3'); // ArithmeticException
|
||||
BigDecimal::of('1/8'); // 0.125
|
||||
BigDecimal::of('1/3'); // ArithmeticException
|
||||
```
|
||||
|
||||
Note about native integers: instantiating from an `int` is safe *as long as you don't exceed the maximum
|
||||
value for your platform* (`PHP_INT_MAX`), in which case it would be transparently converted to `float` by PHP without
|
||||
notice, and could result in a loss of information. In doubt, prefer instantiating from a `string`, which supports
|
||||
an unlimited numbers of digits:
|
||||
|
||||
echo BigInteger::of(999999999999999999999); // 1000000000000000000000
|
||||
echo BigInteger::of('999999999999999999999'); // 999999999999999999999
|
||||
```php
|
||||
echo BigInteger::of(999999999999999999999); // 1000000000000000000000
|
||||
echo BigInteger::of('999999999999999999999'); // 999999999999999999999
|
||||
```
|
||||
|
||||
Note about floating-point values: instantiating from a `float` might be unsafe, as floating-point values are
|
||||
imprecise by design, and could result in a loss of information. Always prefer instantiating from a `string`, which
|
||||
supports an unlimited number of digits:
|
||||
|
||||
echo BigDecimal::of(1.99999999999999999999); // 2
|
||||
echo BigDecimal::of('1.99999999999999999999'); // 1.99999999999999999999
|
||||
```php
|
||||
echo BigDecimal::of(1.99999999999999999999); // 2
|
||||
echo BigDecimal::of('1.99999999999999999999'); // 1.99999999999999999999
|
||||
```
|
||||
|
||||
### Immutability & chaining
|
||||
#### 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:
|
||||
|
||||
$ten = BigInteger::of(10);
|
||||
```php
|
||||
$ten = BigInteger::of(10);
|
||||
|
||||
echo $ten->plus(5); // 15
|
||||
echo $ten->multipliedBy(3); // 30
|
||||
echo $ten->plus(5); // 15
|
||||
echo $ten->multipliedBy(3); // 30
|
||||
```
|
||||
|
||||
The methods can be chained for better readability:
|
||||
|
||||
echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 30
|
||||
```php
|
||||
echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 30
|
||||
```
|
||||
|
||||
### Parameter types
|
||||
#### Parameter types
|
||||
|
||||
All methods that accept a number: `plus()`, `minus()`, `multipliedBy()`, etc. accept the same types as `of()`.
|
||||
For example, given the following number:
|
||||
|
||||
$integer = BigInteger::of(123);
|
||||
```php
|
||||
$integer = BigInteger::of(123);
|
||||
```
|
||||
|
||||
The following lines are equivalent:
|
||||
|
||||
$integer->multipliedBy(123);
|
||||
$integer->multipliedBy('123');
|
||||
$integer->multipliedBy($integer);
|
||||
```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:
|
||||
|
||||
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.0')); // 4
|
||||
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5')); // ArithmeticException
|
||||
echo BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2)); // 5.0
|
||||
```php
|
||||
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.0')); // 4
|
||||
echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5')); // ArithmeticException
|
||||
echo BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2)); // 5.0
|
||||
```
|
||||
|
||||
### Division & rounding
|
||||
#### Division & rounding
|
||||
|
||||
#### BigInteger
|
||||
##### 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:
|
||||
|
||||
echo BigInteger::of(999)->dividedBy(3); // 333
|
||||
echo BigInteger::of(1000)->dividedBy(3); // RoundingNecessaryException
|
||||
```php
|
||||
echo BigInteger::of(999)->dividedBy(3); // 333
|
||||
echo BigInteger::of(1000)->dividedBy(3); // RoundingNecessaryException
|
||||
```
|
||||
|
||||
You can pass an optional [rounding mode](http://brick.io/math/class-Brick.Math.RoundingMode.html) to round the result, if necessary:
|
||||
|
||||
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::DOWN); // 333
|
||||
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::UP); 334
|
||||
```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:
|
||||
|
||||
echo BigInteger::of(1000)->quotient(3); // 333
|
||||
echo BigInteger::of(1000)->remainder(3); // 1
|
||||
```php
|
||||
echo BigInteger::of(1000)->quotient(3); // 333
|
||||
echo BigInteger::of(1000)->remainder(3); // 1
|
||||
```
|
||||
|
||||
You can even get both at the same time:
|
||||
|
||||
list ($quotient, $remainder) = BigInteger::of(1000)->quotientAndRemainder(3);
|
||||
```php
|
||||
list ($quotient, $remainder) = BigInteger::of(1000)->quotientAndRemainder(3);
|
||||
```
|
||||
|
||||
#### BigDecimal
|
||||
##### 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](http://brick.io/math/class-Brick.Math.RoundingMode.html) must be provided.
|
||||
|
||||
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::HALF_DOWN); // 0.12
|
||||
echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HALF_UP); // 0.13
|
||||
```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::HALF_DOWN); // 0.12
|
||||
echo BigDecimal::of(1)->dividedBy('8', 2, RoundingMode::HALF_UP); // 0.13
|
||||
```
|
||||
|
||||
If you know that the division yields a finite number of decimals places, you can use `exactlyDividedBy()`, which will
|
||||
automatically compute the required scale to fit the result, or throw an exception if the division yields an infinite
|
||||
repeating decimal:
|
||||
|
||||
echo BigDecimal::of(1)->exactlyDividedBy(256); // 0.00390625
|
||||
echo BigDecimal::of(1)->exactlyDividedBy(11); // RoundingNecessaryException
|
||||
```php
|
||||
echo BigDecimal::of(1)->exactlyDividedBy(256); // 0.00390625
|
||||
echo BigDecimal::of(1)->exactlyDividedBy(11); // RoundingNecessaryException
|
||||
```
|
||||
|
||||
#### BigRational
|
||||
##### BigRational
|
||||
|
||||
The result of the division of a `BigRational` can always be represented exactly:
|
||||
|
||||
echo BigRational::of('123/456')->dividedBy('7'); // 123/3192
|
||||
echo BigRational::of('123/456')->dividedBy('9/8'); // 984/4104
|
||||
```php
|
||||
echo BigRational::of('123/456')->dividedBy('7'); // 123/3192
|
||||
echo BigRational::of('123/456')->dividedBy('9/8'); // 984/4104
|
||||
```
|
||||
|
||||
### Serialization
|
||||
#### 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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user