You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This library provides immutable classes to work with arbitrary precision numbers:
16
+
17
+
-`BigInteger` — integer number, e.g. `123`
18
+
-`BigDecimal` — decimal number, e.g. `1.23`
19
+
-`BigRational` — fraction, e.g. `2/3`
20
+
21
+
It works with or without the GMP or BCMath PHP extensions, falling back to a pure-PHP implementation if necessary.
22
+
23
+
Unless documented otherwise, all methods either return an exact result or throw an exception if the result is not exact.
24
+
This behaviour can be customized by passing a `RoundingMode` enum to the relevant methods.
25
+
13
26
### Installation
14
27
15
-
This library is installable via [Composer](https://getcomposer.org/):
28
+
This library is installable via [composer](https://getcomposer.org/):
16
29
17
30
```bash
18
31
composer require brick/math
@@ -22,42 +35,40 @@ composer require brick/math
22
35
23
36
This library requires PHP 8.2 or later.
24
37
25
-
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.
26
-
27
38
Although the library can work seamlessly on any PHP installation, it is highly recommended that you install the
28
39
[GMP](http://php.net/manual/en/book.gmp.php) or [BCMath](http://php.net/manual/en/book.bc.php) extension
29
40
to speed up calculations. The fastest available calculator implementation will be automatically selected at runtime.
30
41
31
-
### Project status & release process
32
-
33
-
While this library is still under development, it is well tested and considered stable enough to use in production
34
-
environments.
42
+
### Release process
35
43
36
-
The current releases are numbered `0.x.y`. When a non-breaking change is introduced (adding new methods, optimizing
37
-
existing code, etc.), `y` is incremented.
44
+
This library follows [semantic versioning](https://semver.org/).
38
45
39
-
**When a breaking change is introduced, a new `0.x` version cycle is always started.**
46
+
## Number classes
40
47
41
-
It is therefore safe to lock your project to a given release cycle, such as `^0.14`.
48
+
The three number classes all extend the same `BigNumber` class:
42
49
43
-
If you need to upgrade to a newer release cycle, check the [release history](https://github.com/brick/math/releases)
44
-
for a list of changes introduced by each further `0.x.0` version.
50
+
```
51
+
Brick\Math\BigNumber
52
+
├── Brick\Math\BigInteger
53
+
├── Brick\Math\BigDecimal
54
+
└── Brick\Math\BigRational
55
+
```
45
56
46
-
### Package contents
57
+
`BigNumber` is an abstract class that defines the common behaviour of all number classes:
47
58
48
-
This library provides the following public classes in the `Brick\Math` namespace:
59
+
-`of()` — to obtain an instance
60
+
-`min()`, `max()`, `sum()`
61
+
-`toString()`
62
+
- sign methods: `isZero()`, `isPositive()`, etc.
63
+
- comparison methods: `isEqualTo()`, `isGreaterThan()`, etc.
49
64
50
-
-[BigNumber](https://github.com/brick/math/blob/0.14.7/src/BigNumber.php): base class for `BigInteger`, `BigDecimal` and `BigRational`
51
-
-[BigInteger](https://github.com/brick/math/blob/0.14.7/src/BigInteger.php): represents an arbitrary-precision integer number.
52
-
-[BigDecimal](https://github.com/brick/math/blob/0.14.7/src/BigDecimal.php): represents an arbitrary-precision decimal number.
53
-
-[BigRational](https://github.com/brick/math/blob/0.14.7/src/BigRational.php): represents an arbitrary-precision rational number (fraction), always reduced to lowest terms.
54
-
-[RoundingMode](https://github.com/brick/math/blob/0.14.7/src/RoundingMode.php): enum representing all available rounding modes.
65
+
Comparison methods work across all number classes, you can for example compare a `BigInteger` to a `BigDecimal`, or a `BigDecimal` to a `BigRational`.
55
66
56
-
And [exceptions](#exceptions) in the `Brick\Math\Exception` namespace.
67
+
`BigRational` numbers are always simplified to lowest terms, for example `2/6` is automatically simplified to `1/3`.
57
68
58
-
### Overview
69
+
All classes work with an unlimited number of digits (or, to be exact, limited at ~`PHP_INT_MAX` digits), effectively only limited by available memory and CPU time.
59
70
60
-
####Instantiation
71
+
## Instantiation
61
72
62
73
The constructors of the classes are not public, you must use a factory method to obtain an instance.
All number classes can be converted to string using either the `toString()` method, or the `(string)` cast. For example, the following lines are equivalent:
231
+
232
+
```php
233
+
echo BigInteger::of(123)->toString();
234
+
echo (string) BigInteger::of(123);
235
+
```
236
+
237
+
Different number classes produce different outputs, but will all fold to plain digit strings if they represent a whole number:
238
+
239
+
```php
240
+
echo BigInteger::of(-123)->toString(); // -123
241
+
242
+
echo BigDecimal::of('1.0')->toString(); // 1.0
243
+
echo BigDecimal::of('1')->toString(); // 1
244
+
245
+
echo BigRational::of('2/3')->toString(); // 2/3
246
+
echo BigRational::of('1/1')->toString(); // 1
247
+
```
248
+
249
+
All string outputs are parseable by the `of()` factory method, i.e. this is guaranteed to work:
250
+
251
+
```php
252
+
BigNumber::of($bigNumber->toString());
253
+
```
254
+
255
+
> [!IMPORTANT]
256
+
> Because `BigDecimal::toString()` and `BigRational::toString()` can return whole numbers, some numbers can be returned
257
+
> as `BigInteger` when parsed using `BigNumber::of()`. If you want to retain the original type when reparsing numbers,
258
+
> be sure to use `BigDecimal::of()` or `BigRational::of()`.
259
+
260
+
### BigRational
261
+
262
+
In addition to the standard rational representation such as `2/3`, rational numbers can be represented as decimal numbers
263
+
with a potentially repeating suite of digits. You can use `toRepeatingDecimalString()` to get this representation:
0 commit comments