README

A PHP library to work with arbitrary precision numbers.

Installation

This library is installable viaComposer:

composer require brick/math

Requirements

This library requires PHP 8.1 or later.

For PHP 8.0 compatibility, you can use version0.11. For PHP 7.4, you can use version0.10. For PHP 7.1, 7.2 & 7.3, you can use version0.9. Note thatthese PHP versions are EOL 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 theGMP orBCMath extensionto speed up calculations. The fastest available calculator implementation will be automatically selected at runtime.

Project status & release process

While this library is still under development, it is well tested and considered stable enough to use in productionenvironments.

The current releases are numbered0.x.y. When a non-breaking change is introduced (adding new methods, optimizingexisting code, etc.),y is incremented.

When a breaking change is introduced, a new0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as^0.13.

If you need to upgrade to a newer release cycle, check therelease historyfor a list of changes introduced by each further0.x.0 version.

Package contents

This library provides the following public classes in theBrick\Math namespace:

• BigNumber: base class forBigInteger,BigDecimal andBigRational
• BigInteger: represents an arbitrary-precision integer number.
• BigDecimal: represents an arbitrary-precision decimal number.
• BigRational: represents an arbitrary-precision rational number (fraction).
• RoundingMode: enum representing all available rounding modes.

And the following exceptions in theBrick\Math\Exception namespace:

• MathException: base class for all exceptions
• DivisionByZeroException: thrown when a division by zero occurs
• IntegerOverflowException: thrown when attempting to convert a too largeBigInteger toint
• NumberFormatException: thrown when parsing a number string in an invalid format
• RoundingNecessaryException: thrown when the result of the operation cannot be represented without explicit rounding
• NegativeNumberException: thrown when attempting to calculate the square root of a negative number

Overview

Instantiation

The constructors of the classes are not public, you must use a factory method to obtain an instance.

All classes provide anof() factory method that accepts any of the following types:

• BigNumber instances
• int numbers
• float numbers
• string representations of integer, decimal and rational numbers

Example:

BigInteger::of(123546);BigInteger::of('9999999999999999999999999999999999999999999');BigDecimal::of(1.2);BigDecimal::of('9.99999999999999999999999999999999999999999999');BigRational::of('2/3');BigRational::of('1.1');// 11/10

Note that allof() methods accept all the representations above,as long as it can be safely converted tothe current type:

BigInteger::of('1.00');// 1BigInteger::of('1.01');// RoundingNecessaryExceptionBigDecimal::of('1/8');// 0.125BigDecimal::of('1/3');// RoundingNecessaryException

Note about native integers: instantiating from anint is safeas long as you don't exceed the maximumvalue for your platform (PHP_INT_MAX), in which case it would be transparently converted tofloat by PHP withoutnotice, and could result in a loss of information. In doubt, prefer instantiating from astring, which supportsan unlimited numbers of digits:

echo BigInteger::of(999999999999999999999);// 1000000000000000000000echo BigInteger::of('999999999999999999999');// 999999999999999999999

Note about floating-point values: instantiating from afloat might be unsafe, as floating-point values areimprecise by design, and could result in a loss of information. Always prefer instantiating from astring, whichsupports an unlimited number of digits:

echo BigDecimal::of(1.99999999999999999999);// 2echo BigDecimal::of('1.99999999999999999999');// 1.99999999999999999999

Immutability & chaining

TheBigInteger,BigDecimal andBigRational classes are immutable: their value never changes,so that they can be safely passed around. All methods that return aBigInteger,BigDecimal orBigRationalreturn a new object, leaving the original object unaffected:

$ten = BigInteger::of(10);echo$ten->plus(5);// 15echo$ten->multipliedBy(3);// 30

The methods can be chained for better readability:

echo BigInteger::of(10)->plus(5)->multipliedBy(3);// 45

Parameter types

All methods that accept a number:plus(),minus(),multipliedBy(), etc. accept the same types asof().For example, given the following number:

$integer = BigInteger::of(123);

The following lines are equivalent:

$integer->multipliedBy(123);$integer->multipliedBy('123');$integer->multipliedBy($integer);

Just likeof(), other types ofBigNumber are acceptable, as long as they can be safely converted to the current type:

echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.0'));// 4echo BigInteger::of(2)->multipliedBy(BigDecimal::of('2.5'));// RoundingNecessaryExceptionecho BigDecimal::of(2.5)->multipliedBy(BigInteger::of(2));// 5.0

Division & rounding

BigInteger

By default, dividing aBigInteger returns the exact result of the division, or throws an exception if the remainderof the division is not zero:

echo BigInteger::of(999)->dividedBy(3);// 333echo BigInteger::of(1000)->dividedBy(3);// RoundingNecessaryException

You can pass an optionalrounding mode to round the result, if necessary:

echo BigInteger::of(1000)->dividedBy(3, RoundingMode::DOWN);// 333echo BigInteger::of(1000)->dividedBy(3, RoundingMode::UP);// 334

If you're into quotients and remainders, there are methods for this, too:

echo BigInteger::of(1000)->quotient(3);// 333echo BigInteger::of(1000)->remainder(3);// 1

You can even get both at the same time:

[$quotient,$remainder] = BigInteger::of(1000)->quotientAndRemainder(3);

BigDecimal

Dividing aBigDecimal always requires a scale to be specified. If the exact result of the division does not fit inthe given scale, arounding mode must be provided.

echo BigDecimal::of(1)->dividedBy('8',3);// 0.125echo BigDecimal::of(1)->dividedBy('8',2);// RoundingNecessaryExceptionecho BigDecimal::of(1)->dividedBy('8',2, RoundingMode::HALF_DOWN);// 0.12echo BigDecimal::of(1)->dividedBy('8',2, RoundingMode::HALF_UP);// 0.13

If you know that the division yields a finite number of decimals places, you can useexactlyDividedBy(), which willautomatically compute the required scale to fit the result, or throw an exception if the division yields an infiniterepeating decimal:

echo BigDecimal::of(1)->exactlyDividedBy(256);// 0.00390625echo BigDecimal::of(1)->exactlyDividedBy(11);// RoundingNecessaryException

BigRational

The result of the division of aBigRational can always be represented exactly:

echo BigRational::of('123/456')->dividedBy('7');// 123/3192echo BigRational::of('123/456')->dividedBy('9/8');// 984/4104

Bitwise operations

BigInteger supports bitwise operations:

• and()
• or()
• xor()
• not()

and bit shifting:

• shiftedLeft()
• shiftedRight()

Serialization

BigInteger,BigDecimal andBigRational 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 extensioninstalled will still work as expected.