Loheide-eu-mitarbeiterplatt.../vendor/brick/math/README.md
Friederich Loheide 9c0f8de791
Some checks failed
CI / PHP 8.3 / mariadb:10.6 (pull_request) Successful in 1m14s
CI / PHP 8.4 / mariadb:10.6 (pull_request) Successful in 1m12s
CI / PHP 8.4 / mariadb:11.4 (pull_request) Successful in 1m7s
CI / PHP 8.3 / mariadb:11.4 (pull_request) Successful in 1m19s
CI / PHP 8.3 / mysql:8.0 (pull_request) Successful in 1m32s
CI / PHP 8.4 / mysql:8.0 (pull_request) Successful in 1m22s
CI / PHP 8.4 / mysql:8.4 (pull_request) Successful in 1m32s
CI / PHP 8.3 / mysql:8.4 (pull_request) Successful in 1m35s
CI / Build-Artefakte aktuell (pull_request) Failing after 1m7s
Phase 0: Fundament für Inhaus
- Laravel 13 mit Filament 5 (Admin), Inertia 3 + Vue 3 + Vuetify 4 (Material 3)
- Anmeldung über Fortify (Login, Passwort vergessen/ändern), keine Selbstregistrierung
- Profil mit Profilbild (WebP in festen Größen), Personenseiten, Header mit Avatar-Menü
- Material-3-Farbschema aus der Primärfarbe, hell/dunkel/System pro Person
- Basis-Branding (Portalname, Logo, Primärfarbe) im Admin unter „Erscheinungsbild“
- Benutzerverwaltung im Admin, Zugang vorläufig über is_admin
- vendor/ (ohne Dev-Pakete) und Frontend-Build mitversioniert, Dev-Pakete in vendor-dev/
- PHPUnit-Tests gegen MySQL/MariaDB, Forgejo-CI-Matrix, Docker-Entwicklungsumgebung
- VERSION, CHANGELOG.md und CONTRIBUTING.md mit Release-Ablauf

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 20:35:30 +00:00

534 lines
19 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.
[![Build Status](https://github.com/brick/math/workflows/CI/badge.svg)](https://github.com/brick/math/actions)
[![Coverage Status](https://codecov.io/github/brick/math/graph/badge.svg)](https://codecov.io/github/brick/math)
[![Latest Stable Version](https://poser.pugx.org/brick/math/v/stable)](https://packagist.org/packages/brick/math)
[![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)](https://opensource.org/license/MIT)
## Introduction
This library provides immutable classes to work with three types of numbers:
- `BigInteger` — an integer number such as `123`
- `BigDecimal` — a decimal number such as `1.23`
- `BigRational` — a fraction such as `2/3` — always reduced to lowest terms, e.g. `2/6` becomes `1/3`
It automatically uses GMP or BCMath when available, and falls back to a pure-PHP implementation otherwise.
All classes work with a virtually **unlimited number of digits**, and are only limited by available memory and CPU time.
### Installation
This library is installable via [Composer](https://getcomposer.org/):
```bash
composer require brick/math
```
### Requirements
This library requires PHP 8.2 or later.
Although the library can work seamlessly on any PHP installation, it is highly recommended that you install the
[GMP](https://php.net/manual/en/book.gmp.php) or [BCMath](https://php.net/manual/en/book.bc.php) extension
to speed up calculations. The fastest available calculator implementation will be automatically selected at runtime.
## Number classes
The three number classes all extend the same `BigNumber` class:
```
Brick\Math\BigNumber
├── BigInteger
├── BigDecimal
└── BigRational
```
`BigNumber` is an abstract class that defines the common behaviour of all number classes:
- `of()` — to obtain an instance
- sign methods: `isZero()`, `isPositive()`, etc.
- comparison methods: `isEqualTo()`, `isGreaterThan()`, etc.
- `min()`, `max()`, `sum()`, `toString()`, etc.
## Instantiation
The constructors of the classes are not public, so 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(123456);
BigInteger::of('9999999999999999999999999999999999999999999');
BigDecimal::of('9.99999999999999999999999999999999999999999999');
BigDecimal::of('1.23e1000');
BigRational::of('2/3');
```
The `of()` method of each class accepts all the representations above, *as long as the value can be safely converted to that class*:
```php
BigInteger::of('1e3'); // 1000
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
```
> [!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
> ```
## Parsing untrusted input
`of()` places no hard limits on its input: a string with millions of digits is accepted as is, and a number in
exponential notation is expanded to its full length, so a string as short as `1e1000000000` yields a number with
a billion digits.
If your input comes from an untrusted source, such as an HTTP request, use `parse()` instead, which requires you
to specify the allowed syntax and a maximum number of digits:
```php
use Brick\Math\NumberSyntax;
BigDecimal::parse($input, allowedSyntax: NumberSyntax::DECIMAL, maxDigits: 20);
```
The `$allowedSyntax` parameter restricts the accepted notations. Plain integers such as `123` are always accepted,
and each `NumberSyntax` case (`DecimalPoint`, `Exponent`, `Fraction`) allows one additional feature. The enum also
provides constants for the most common combinations:
- `NumberSyntax::INTEGER` — integers only: `123`
- `NumberSyntax::DECIMAL` — integers and decimal numbers: `123`, `123.45`; typical for monetary input
- `NumberSyntax::SCIENTIFIC` — integers, decimal numbers and exponents: `123`, `123.45`, `1.5e-3`; accepts every JSON number
- `NumberSyntax::RATIONAL` — integers and fractions: `123`, `22/7`
- `NumberSyntax::ALL` — the full syntax accepted by `of()`: `123`, `123.45`, `1.5e-3`, `22/7`
The `$maxDigits` parameter limits the number of digits, counted both as written in the input and in the resulting number,
so that a value such as `1e1000000000` is rejected before it is ever expanded:
```php
BigDecimal::parse('123.45', allowedSyntax: NumberSyntax::DECIMAL, maxDigits: 20); // 123.45
BigDecimal::parse('1.2e3', allowedSyntax: NumberSyntax::DECIMAL, maxDigits: 20); // NumberFormatException (exponent not allowed)
BigDecimal::parse('1e1000000000', allowedSyntax: NumberSyntax::SCIENTIFIC, maxDigits: 20); // NumberFormatException (too many digits)
```
## 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);
```
As with `of()`, other types of numbers are accepted, as long as they can be safely converted to the current type:
```php
echo BigInteger::of(2)->multipliedBy('2.0'); // 4
echo BigInteger::of(2)->multipliedBy('2.5'); // RoundingNecessaryException
echo BigDecimal::of('2.5')->multipliedBy(2); // 5.0
```
These parameters are converted with `of()`, so the same rules apply: for untrusted strings, use
[`parse()`](#parsing-untrusted-input) first, and pass the resulting number to the method.
## 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
```
## Rounding
Unless documented otherwise, all methods either return an exact result or throw an exception if the result is not exact.
Where applicable, this behaviour is 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. |
| `RoundingMode::HalfOdd` | Rounds to nearest; ties to the odd neighbor. |
See the [Division](#division) section for examples of `RoundingMode` in action.
> [!TIP]
> PHP 8.4 introduced a native [RoundingMode](https://www.php.net/manual/en/enum.roundingmode.php) enum, used by
> `round()`, `bcround()` and `BcMath\Number::round()`. If you already have a native rounding mode at hand, you can
> convert it to its `Brick\Math` equivalent:
>
> ```php
> $roundingMode = RoundingMode::fromNativeRoundingMode(\RoundingMode::HalfAwayFromZero);
> ```
## 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('3.4')->multipliedBy('5.6'); // 25.76
echo BigRational::of('2/3')->plus('5/6')->multipliedBy('5/4'); // 15/8
```
The scale of `BigDecimal` operation results is predictable:
- for addition and subtraction, it is the larger of the two operand scales;
- for multiplication, it is the sum of the operand scales.
`BigRational` results are automatically reduced to lowest terms.
### Division
Division uses a class-specific API because exactness and precision rules differ between integers, decimals, and rationals.
#### 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 `RoundingMode` 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
```
You can also compute quotients and remainders:
```php
echo BigInteger::of(1000)->quotient(3); // 333
echo BigInteger::of(1000)->remainder(3); // 1
```
You can also get both in one call:
```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 `RoundingMode` 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 decimal 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
```
`BigRational` results are automatically reduced to lowest terms.
### Other arithmetic operations
In addition to `plus()`, `minus()`, `multipliedBy()`, and `dividedBy()`, the library provides:
- exponentiation with `power()` on all number classes
- square root with `sqrt()` on `BigInteger` and `BigDecimal`
- nth root with `nthRoot()` on `BigInteger` and `BigDecimal`
- greatest common divisor / least common multiple with `gcd()`, `lcm()`, `gcdAll()`, `lcmAll()` on `BigInteger`
- modular arithmetic with `mod()`, `modInverse()`, and `modPow()` on `BigInteger`
- reciprocal with `reciprocal()` on `BigRational`
- decimal-point shifts with `withPointMovedLeft()` and `withPointMovedRight()` on `BigDecimal`
## 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
- `isZero()`
- `isNegative()`
- `isNegativeOrZero()`
- `isPositive()`
- `isPositiveOrZero()`
For sign-related transformations, use:
- `abs()` — returns the absolute value
- `negated()` — returns the opposite value
### Comparison methods
Comparison works across all number classes (`BigInteger`, `BigDecimal`, `BigRational`):
- `compareTo()` — returns `-1`, `0`, or `1` if this number is `<`, `=`, or `>` the given number
- `isEqualTo()`
- `isLessThan()`
- `isLessThanOrEqualTo()`
- `isGreaterThan()`
- `isGreaterThanOrEqualTo()`
You can also use `min()`, `max()`, and `clamp()` to compare and bound values.
## Type conversion
### Conversion to other number classes
All classes provide the following methods:
- `toBigInteger()`
- `toBigDecimal()`
- `toBigRational()`
`toBigInteger()` and `toBigDecimal()` either return an exact result, or throw a `RoundingNecessaryException` if the conversion is not exact.
`toBigRational()` always returns an exact result.
You can also convert any number to a `BigDecimal` with a given scale, rounding the result if necessary:
```php
echo BigRational::of('2/3')->toScale(5, RoundingMode::Up); // 0.66667
```
To convert any number to a `BigInteger` with rounding, use:
```php
echo BigRational::of('10/3')->toScale(0, RoundingMode::Up)->toBigInteger(); // 4
```
### Conversion to native numbers
All classes provide the following methods:
- `toInt()` — converts exactly to an `int` if possible, or throws an exception otherwise
- `toFloat()` — returns an approximation of the number as a `float` (may be infinite)
> [!WARNING]
> `toFloat()` is the only method of the library that returns an approximation. Use it with caution.
### Conversion to string
All number classes can be converted to string using either the `toString()` method or the `(string)` cast. For example, the following lines are equivalent:
```php
echo BigInteger::of(123)->toString();
echo (string) BigInteger::of(123);
```
Different number classes produce different outputs. Note that a `BigDecimal` with a scale of zero and a `BigRational` with a denominator of one both print as plain digit strings:
```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());
```
> [!IMPORTANT]
> Because `BigDecimal::toString()` and `BigRational::toString()` can return whole numbers, these numbers will be parsed
> as `BigInteger` when using `BigNumber::of()`. If you want to retain the original type when reparsing numbers, be sure
> to use `of()` on the specific class: `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.
> [!NOTE]
> The `of()` and `parse()` factory methods do not accept decimal strings with repeating periods.
> [!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.
## Base conversion
`BigInteger` can parse and format numbers in different bases:
- `fromBase()` / `toBase()` for bases 2 to 36 (case-insensitive input, lowercase output above base 10)
- `fromArbitraryBase()` / `toArbitraryBase()` for custom single-byte alphabets
```php
echo BigInteger::fromBase('ff', 16); // 255
echo BigInteger::of(255)->toBase(16); // ff
echo BigInteger::fromArbitraryBase('bab', 'ab'); // 5
echo BigInteger::of(5)->toArbitraryBase('ab'); // bab
```
You can also convert to and from byte strings using `fromBytes()` and `toBytes()`.
## Bitwise operations
`BigInteger` supports bitwise operations:
- `and()`
- `or()`
- `xor()`
- `not()`
and bit shifting:
- `shiftedLeft()`
- `shiftedRight()`
Bit-level inspection helpers are also available:
- `getBitLength()`
- `getLowestSetBit()`
- `isBitSet()`
## Random number generation
`BigInteger` provides factory methods for random integers:
- `randomBits($bitCount)` returns a non-negative integer with up to the requested bit length.
- `randomRange($min, $max)` returns a value in the inclusive range `[$min, $max]`.
Both methods use a secure random source by default and throw `RandomSourceException` if randomness cannot be obtained.
## 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\BigInteger;
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 documented in each method:
- `DivisionByZeroException`
- `IntegerOverflowException`
- `InvalidArgumentException`
- `NegativeNumberException`
- `NoInverseException`
- `NumberFormatException`
- `PlatformException`
- `RandomSourceException`
- `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.
### JSON
All number classes support serialization to JSON using the `json_encode()` function:
```php
echo json_encode(BigInteger::of(123)); // "123"
```
## Additional information
### Release process
This library follows [semantic versioning](https://semver.org/).
### 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.