Brick\Math

Install the library using Composer to add it to your PHP project.

composer require brick/math

PHP Version Compatibility

• PHP 8.2+: Use the latest version.
• PHP 8.1: Use version 0.13.
• PHP 8.0: Use version 0.11.
• PHP 7.4: Use version 0.10.
• PHP 7.1, 7.2, 7.3: Use version 0.9.

Recommended Extensions

While the library works on any PHP installation, it is highly recommended to install the GMP or BCMath extensions to speed up calculations. The fastest available implementation is automatically selected at runtime.

BigInteger supports standard bitwise operations and bit shifting:

• and()
• or()
• xor()
• not()
• shiftedLeft()
• shiftedRight()

Division in BigRational always results in an exact representation, as it returns a new rational number (fraction) reduced to its lowest terms.

echo BigRational::of('13/99')->dividedBy('7'); // 13/693
echo BigRational::of('13/99')->dividedBy('9/8'); // 104/891

Dividing a BigDecimal requires specifying a scale. If the result cannot be represented within that scale, you must provide a RoundingMode.

Alternatively, use dividedByExact() to automatically compute the required scale, which will throw a RoundingNecessaryException if the division results in an infinite repeating decimal.

By default, BigInteger::dividedBy() returns the exact result or throws a RoundingNecessaryException if there is a remainder.

To handle remainders, you can:

1. Provide a RoundingMode to dividedBy().
2. Use quotient() to get the integer part.
3. Use remainder() to get the remainder.
4. Use quotientAndRemainder() to get both at once.

// Default (throws exception if remainder exists)
echo BigInteger::of(999)->dividedBy(3); // 333
// echo BigInteger::of(1000)->dividedBy(3); // Throws RoundingNecessaryException

// Using RoundingMode
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::Down); // 333
echo BigInteger::of(1000)->dividedBy(3, RoundingMode::Up); // 334

// Quotient and Remainder
echo BigInteger::of(1000)->quotient(3); // 333
echo BigInteger::of(1000)->remainder(3); // 1
[$quotient, $remainder] = BigInteger::of(1000)->quotientAndRemainder(3);

Constructors for BigInteger, BigDecimal, and BigRational are not public. You must use the of() factory method. The of() method accepts BigNumber instances, int numbers, or string representations.

Note: of() does not accept float values to avoid precision loss. To convert a float, use fromFloatExact() or fromFloatShortest().

All exceptions in this library implement the Brick\\Math\ Exception\ MathException interface. You can catch all library-specific errors using this interface, or catch specific exceptions for granular error handling.

```php
use Brick\\\Math\
BigDecimal;
use Brick\Math\Exception\MathException;

try {
    $number = BigInteger::of(1)->dividedBy(3);
} catch (MathException $e) {
    // Catches all Brick\Math exceptions
}

Specific Exception Classes:

• DivisionByZeroException
• IntegerOverflowException
• InvalidArgumentException
• NegativeNumberException
• NoInverseException
• NumberFormatException
• RandomSourceException
• RoundingNecessaryException
• UnsupportedPlatformException