Update README

[skip CI]

Author: BenMorel

README.md

@@ -1,4 +1,4 @@
-## Brick\Math
+# Brick\Math
 
 <img src="https://raw.githubusercontent.com/brick/brick/master/logo.png" alt="" align="left" height="64">
 
@@ -10,6 +10,16 @@ A PHP library to work with arbitrary precision numbers.
 [![Total Downloads](https://poser.pugx.org/brick/math/downloads)](https://packagist.org/packages/brick/math)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://opensource.org/licenses/MIT)
 
+## Introduction
+
+This library provides immutable classes to work with numbers of any size:
+
+- `BigInteger` — an integer number such as `123`
+- `BigDecimal` — a decimal number such as `1.23`
+- `BigRational` — a fraction such as `2/3`
+
+It works with or without the GMP or BCMath extensions, falling back to a pure-PHP implementation if necessary.
+
 ### Installation
 
 This library is installable via [Composer](https://getcomposer.org/):
@@ -22,42 +32,35 @@ composer require brick/math
 
 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
+## Number classes
 
-While this library is still under development, it is well tested and considered stable enough to use in production
-environments.
+The three number classes all extend the same `BigNumber` class:
 
-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.14`.
-
-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.
+```
+Brick\Math\BigNumber
+├── Brick\Math\BigInteger
+├── Brick\Math\BigDecimal
+└── Brick\Math\BigRational
+```
 
-### Package contents
+`BigNumber` is an abstract class that defines the common behaviour of all number classes:
 
-This library provides the following public classes in the `Brick\Math` namespace:
+- `of()` — to obtain an instance
+- sign methods: `isZero()`, `isPositive()`, etc.
+- comparison methods: `isEqualTo()`, `isGreaterThan()`, etc.
+- `min()`, `max()`, `sum()`, `toString()` etc.
 
-- [BigNumber](https://github.com/brick/math/blob/0.14.7/src/BigNumber.php): base class for `BigInteger`, `BigDecimal` and `BigRational`
-- [BigInteger](https://github.com/brick/math/blob/0.14.7/src/BigInteger.php): represents an arbitrary-precision integer number.
-- [BigDecimal](https://github.com/brick/math/blob/0.14.7/src/BigDecimal.php): represents an arbitrary-precision decimal number.
-- [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.
-- [RoundingMode](https://github.com/brick/math/blob/0.14.7/src/RoundingMode.php): enum representing all available rounding modes.
+Comparison methods work across all number classes, you can for example compare a `BigInteger` to a `BigDecimal`, or a `BigDecimal` to a `BigRational`.
 
-And [exceptions](#exceptions) in the `Brick\Math\Exception` namespace.
+All classes work with a virtually unlimited number of digits, and are limited only by available memory and CPU time.
 
-### Overview
+`BigRational` numbers are always simplified to lowest terms, for example `2/6` is automatically simplified to `1/3`.
 
-#### Instantiation
+## Instantiation
 
 The constructors of the classes are not public, you must use a factory method to obtain an instance.
 
@@ -89,7 +92,7 @@ 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)
+BigRational::of('1.15'); // 23/20
 ```
 
 > [!NOTE]
@@ -107,7 +110,7 @@ BigRational::of('1.15'); // 23/20 (reduced to lowest terms)
 > BigDecimal::of((string) $float);
 > ```
 
-#### 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`
@@ -126,7 +129,7 @@ The methods can be chained for better readability:
 echo BigInteger::of(10)->plus(5)->multipliedBy(3); // 45
 ```
 
-#### 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:
@@ -151,9 +154,43 @@ echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5')); // RoundingNecessar
 echo BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2)); // 5.0
 ```
 
-#### Division & rounding
+## Rounding
+
+Unless documented otherwise, all methods either return an exact result or throw an exception if the result is not exact.
+This is typically configurable through an optional `RoundingMode` parameter:
+
+| Rounding mode               | Description                                                   |
+|-----------------------------|---------------------------------------------------------------|
+| `RoundingMode::Unnecessary` | Requires an exact result; throws if rounding would be needed. |
+| `RoundingMode::Up`          | Rounds away from zero.                                        |
+| `RoundingMode::Down`        | Rounds toward zero.                                           |
+| `RoundingMode::Ceiling`     | Rounds toward positive infinity.                              |
+| `RoundingMode::Floor`       | Rounds toward negative infinity.                              |
+| `RoundingMode::HalfUp`      | Rounds to nearest; ties away from zero.                       |
+| `RoundingMode::HalfDown`    | Rounds to nearest; ties toward zero.                          |
+| `RoundingMode::HalfCeiling` | Rounds to nearest; ties toward positive infinity.             |
+| `RoundingMode::HalfFloor`   | Rounds to nearest; ties toward negative infinity.             |
+| `RoundingMode::HalfEven`    | Rounds to nearest; ties to the even neighbor.                 |
+
+See the next section for examples of `RoundingMode` in action.
+
+## Arithmetic operations
+
+### Addition, subtraction and multiplication
+
+These operations are straightforward on all number classes:
+
+```php
+echo BigInteger::of(1)->plus(2)->multipliedBy(3); // 9
+echo BigDecimal::of('1.2')->plus(BigDecimal::of('3.4'))->multipliedBy('5.6'); // 25.76
+echo BigRational::of('2/3')->plus('5/6')->multipliedBy('5/4'); // 15/8
+```
+
+### Division
 
-##### BigInteger
+Division needs a specific API for each number class:
+
+#### 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:
@@ -163,7 +200,7 @@ 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.14.7/src/RoundingMode.php) to round the result, if necessary:
+You can pass an optional `RoundingMode` to round the result, if necessary:
 
 ```php
 echo BigInteger::of(1000)->dividedBy(3, RoundingMode::Down); // 333
@@ -183,10 +220,10 @@ You can even get both at the same time:
 [$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](https://github.com/brick/math/blob/0.14.7/src/RoundingMode.php) must be provided.
+the given scale, a `RoundingMode` must be provided.
 
 ```php
 echo BigDecimal::of(1)->dividedBy('8', 3); // 0.125
@@ -204,7 +241,7 @@ echo BigDecimal::of(1)->dividedByExact(256); // 0.00390625
 echo BigDecimal::of(1)->dividedByExact(11); // RoundingNecessaryException
 ```
 
-##### BigRational
+#### BigRational
 
 The result of the division of a `BigRational` can always be represented exactly:
 
@@ -213,21 +250,104 @@ 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:
+## String conversion
 
-- `and()`
-- `or()`
-- `xor()`
-- `not()`
+All number classes can be converted to string using either the `toString()` method, or the `(string)` cast. For example, the following lines are equivalent:
 
-and bit shifting:
+```php
+echo BigInteger::of(123)->toString();
+echo (string) BigInteger::of(123);
+```
 
-- `shiftedLeft()`
-- `shiftedRight()`
+Different number classes produce different outputs, but will all fold to plain digit strings if they represent a whole number:
+
+```php
+echo BigInteger::of(-123)->toString(); // -123
+
+echo BigDecimal::of('1.0')->toString(); // 1.0
+echo BigDecimal::of('1')->toString(); // 1
+
+echo BigRational::of('2/3')->toString(); // 2/3
+echo BigRational::of('1/1')->toString(); // 1
+```
+
+All string outputs are parseable by the `of()` factory method. The following is guaranteed to work:
+
+```php
+BigNumber::of($bigNumber->toString());
+```
 
-#### Exceptions
+> [!IMPORTANT]
+> Because `BigDecimal::toString()` and `BigRational::toString()` can return whole numbers, some numbers can be returned
+> as `BigInteger` when parsed using `BigNumber::of()`. If you want to retain the original type when reparsing numbers,
+> be sure to use `BigDecimal::of()` or `BigRational::of()`.
+
+### BigRational to decimal string
+
+In addition to the standard rational representation such as `2/3`, rational numbers can be represented as decimal numbers
+with a potentially repeating sequence of digits. You can use `toRepeatingDecimalString()` to get this representation:
+
+```php
+BigRational::of('1/2')->toRepeatingDecimalString(); // 0.5
+BigRational::of('2/3')->toRepeatingDecimalString(); // 0.(6)
+BigRational::of('171/70')->toRepeatingDecimalString(); // 2.4(428571)
+```
+
+The part in parentheses is the repeating period, if any.
+
+> [!WARNING]
+> `BigRational::toRepeatingDecimalString()` is unbounded.
+> The repeating period can be as large as `denominator - 1`, so large denominators can require a lot of memory and CPU time.
+> Example: `BigRational::of('1/100019')->toRepeatingDecimalString()` has a repeating period of 100,018 digits.
+
+## Sign and comparison
+
+All number classes share the same sign and comparison methods through `BigNumber`.
+
+### Sign methods
+
+Use these methods to inspect the sign of a number:
+
+- `getSign()` returns `-1`, `0`, or `1` for values `< 0`, `= 0`, and `> 0`, respectively.
+- `isNegative()`
+- `isNegativeOrZero()`
+- `isZero()`
+- `isPositiveOrZero()`
+- `isPositive()`
+
+```php
+$n = BigDecimal::of('-12.5');
+
+$n->getSign(); // -1
+$n->isNegative(); // true
+$n->isZero(); // false
+```
+
+### Comparison methods
+
+Comparison works across all number classes (`BigInteger`, `BigDecimal`, `BigRational`):
+
+- `compareTo()` returns `-1`, `0`, or `1` if this number is `<`, `=`, or `>` than the given number.
+- `isEqualTo()`
+- `isLessThan()`
+- `isLessThanOrEqualTo()`
+- `isGreaterThan()`
+- `isGreaterThanOrEqualTo()`
+
+```php
+$a = BigInteger::of('10');
+$b = BigDecimal::of('10.0');
+$c = BigRational::of('21/2');
+
+$a->compareTo('11'); // -1
+$a->isEqualTo($b); // true
+$c->isGreaterThan($a); // true
+```
+
+You can also use `min()`, `max()`, and `clamp()` to compare and bound values.
+
+## 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:
@@ -237,26 +357,45 @@ use Brick\Math\BigDecimal;
 use Brick\Math\Exception\MathException;
 
 try {
-    $number = BigDecimal::of('1.234')->dividedBy(3);
+    $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:
+If you need more granular control over the exceptions thrown, you can catch the specific exception classes documented in each method:
 
 - `DivisionByZeroException`
 - `IntegerOverflowException`
 - `InvalidArgumentException`
 - `NegativeNumberException`
 - `NoInverseException`
 - `NumberFormatException`
+- `RandomSourceException`
 - `RoundingNecessaryException`
 
-#### Serialization
+## Bitwise operations
+
+`BigInteger` supports bitwise operations:
+
+- `and()`
+- `or()`
+- `xor()`
+- `not()`
+
+and bit shifting:
+
+- `shiftedLeft()`
+- `shiftedRight()`
+
+## 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.
+
+## Release process
+
+This library follows [semantic versioning](https://semver.org/).