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 extensions, falling back to a pure-PHP implementation if necessary.
22
+
13
23
### Installation
14
24
15
-
This library is installable via [Composer](https://getcomposer.org/):
25
+
This library is installable via [composer](https://getcomposer.org/):
16
26
17
27
```bash
18
28
composer require brick/math
@@ -22,42 +32,39 @@ composer require brick/math
22
32
23
33
This library requires PHP 8.2 or later.
24
34
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
35
Although the library can work seamlessly on any PHP installation, it is highly recommended that you install the
28
36
[GMP](http://php.net/manual/en/book.gmp.php) or [BCMath](http://php.net/manual/en/book.bc.php) extension
29
37
to speed up calculations. The fastest available calculator implementation will be automatically selected at runtime.
30
38
31
-
### Project status & release process
39
+
### Release process
32
40
33
-
While this library is still under development, it is well tested and considered stable enough to use in production
34
-
environments.
41
+
This library follows [semantic versioning](https://semver.org/).
35
42
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.
43
+
## Number classes
38
44
39
-
**When a breaking change is introduced, a new `0.x` version cycle is always started.**
45
+
The three number classes all extend the same `BigNumber` class:
40
46
41
-
It is therefore safe to lock your project to a given release cycle, such as `^0.14`.
42
-
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.
47
+
```
48
+
Brick\Math\BigNumber
49
+
├── Brick\Math\BigInteger
50
+
├── Brick\Math\BigDecimal
51
+
└── Brick\Math\BigRational
52
+
```
45
53
46
-
### Package contents
54
+
`BigNumber` is an abstract class that defines the common behaviour of all number classes:
47
55
48
-
This library provides the following public classes in the `Brick\Math` namespace:
56
+
-`of()` — to obtain an instance
57
+
- sign methods: `isZero()`, `isPositive()`, etc.
58
+
- comparison methods: `isEqualTo()`, `isGreaterThan()`, etc.
59
+
-`min()`, `max()`, `sum()`, `toString()` etc.
49
60
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.
61
+
Comparison methods work across all number classes, you can for example compare a `BigInteger` to a `BigDecimal`, or a `BigDecimal` to a `BigRational`.
55
62
56
-
And [exceptions](#exceptions) in the `Brick\Math\Exception` namespace.
63
+
All classes work with a virtually unlimited number of digits, and are limited only by available memory and CPU time.
57
64
58
-
### Overview
65
+
`BigRational` numbers are always simplified to lowest terms, for example `2/6` is automatically simplified to `1/3`.
59
66
60
-
####Instantiation
67
+
## Instantiation
61
68
62
69
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:
247
+
248
+
```php
249
+
echo BigInteger::of(123)->toString();
250
+
echo (string) BigInteger::of(123);
251
+
```
252
+
253
+
Different number classes produce different outputs, but will all fold to plain digit strings if they represent a whole number:
254
+
255
+
```php
256
+
echo BigInteger::of(-123)->toString(); // -123
257
+
258
+
echo BigDecimal::of('1.0')->toString(); // 1.0
259
+
echo BigDecimal::of('1')->toString(); // 1
260
+
261
+
echo BigRational::of('2/3')->toString(); // 2/3
262
+
echo BigRational::of('1/1')->toString(); // 1
263
+
```
264
+
265
+
All string outputs are parseable by the `of()` factory method, i.e. this is guaranteed to work:
266
+
267
+
```php
268
+
BigNumber::of($bigNumber->toString());
269
+
```
270
+
271
+
> [!IMPORTANT]
272
+
> Because `BigDecimal::toString()` and `BigRational::toString()` can return whole numbers, some numbers can be returned
273
+
> as `BigInteger` when parsed using `BigNumber::of()`. If you want to retain the original type when reparsing numbers,
274
+
> be sure to use `BigDecimal::of()` or `BigRational::of()`.
275
+
276
+
### Converting BigRational to decimal string
277
+
278
+
In addition to the standard rational representation such as `2/3`, rational numbers can be represented as decimal numbers
279
+
with a potentially repeating suite of digits. You can use `toRepeatingDecimalString()` to get this representation:
0 commit comments