✨ New features

• New exception class: PlatformException (replaces UnsupportedPlatformException)
• PlatformException is now thrown when preg_match() fails due to improper PHP configuration
• PlatformException is now thrown when PHP_INT_SIZE is an unsupported value

🗑️ Deprecations

• Exception class UnsupportedPlatformException is deprecated; catch PlatformException instead

✨ New features

• New rounding mode: RoundingMode::HalfOdd
• New method: RoundingMode::fromNativeRoundingMode() converts from a native PHP RoundingMode enum (PHP 8.4+)

💥 Breaking changes

The following breaking change only affects you if you're using named arguments:

• BigInteger::fromBytes() now uses $bytes as the parameter name

🐛 Bug fixes

• of() no longer accepts a trailing newline (\n) in the input string; such input now throws NumberFormatException
• of() now consistently throws NumberFormatException for exponents too large to process, instead of IntegerOverflowException in some cases
• BigInteger::fromBase() now reports the invalid character with its original case in the NumberFormatException message, instead of lower-casing it

⚡️ Performance improvements

• BigInteger::gcd() no longer exhausts memory on large inputs when the GMP extension is not installed
• BigInteger::modInverse() no longer exhausts memory on large inputs, and is faster when the GMP extension is not installed

👌 Static analysis improvements

• Narrowed parameter and return types with static analysis annotations:
  • nthRoot()'s $n is now positive-int
  • BigInteger::toBase(), toArbitraryBase(), toBytes() and BigRational::toRepeatingDecimalString() now return non-empty-string

✨ New features

• New methods: BigInteger::nthRoot() and BigDecimal::nthRoot() compute the nth root of a number (#113 by @Pablo1Gustavo)

👌 Improvements

• More precise float approximations in BigRational::toFloat()

💥 Breaking changes

• Deprecated method BigDecimal::hasNonZeroFractionalPart() has been removed, use ! $number->getFractionalPart()->isZero() instead
• Exception constructors and factory methods are now @internal

✨ Compatibility improvements

• BigDecimal::fromFloatExact() now supports 32-bit PHP

✨ New features

New methods to create a BigDecimal from a float value:

• BigDecimal::fromFloatExact()
• BigDecimal::fromFloatShortest()

👌 Improvements

• Add @return non-empty-string to toString(), jsonSerialize() and __toString() (#111 by @vudaltsov)

💥 Breaking changes

• BigInteger::getLowestSetBit() now returns null instead of -1 when the number is zero
• Deprecated method BigRational::simplified() has been removed, as it is now a no-op

✨ New features

• New method: BigDecimal::getIntegralPart() returns the integral part as BigInteger (this method existed with a different signature in version 0.14, and was removed in 0.15)
• New method: BigDecimal::getFractionalPart() returns the fractional part as BigDecimal (this method existed with a different signature and meaning in version 0.14, and was removed in 0.15)

🗑️ Deprecations

• Method BigDecimal::hasNonZeroFractionalPart() is deprecated, use ->getFractionalPart()->isZero() instead

💥 Breaking changes

• floating-point inputs are no longer accepted by of() and arithmetic methods, use of((string) $float) to get the same behaviour as before (#105)
• BigRational is now always simplified to lowest terms: all operations, including of() and ofFraction(), now return a fraction in its simplest form (e.g. 2/3 instead of 4/6)
• BigDecimal::dividedBy() now requires the $scale parameter
• BigInteger::sqrt() and BigDecimal::sqrt() now default to RoundingMode::Unnecessary, explicitly pass RoundingMode::Down to get the previous behaviour
• BigInteger::mod() now uses Euclidean modulo semantics: the modulus must be strictly positive, and the result is always non-negative; this change aligns with Java's BigInteger.mod() behaviour
• BigInteger::mod(), modInverse() and modPow() now throw InvalidArgumentException (instead of NegativeNumberException) for negative modulus/exponent arguments
• MathException is now an interface instead of a class
• BigDecimal::getPrecision() now returns 1 for zero values
• BigNumber::min(), max() and sum() now throw an ArgumentCountError when called with no arguments (previously threw InvalidArgumentException)
• BigInteger::randomBits() and randomRange() now throw RandomSourceException when random byte generation fails or returns invalid data

Deprecated API elements removed:

• deprecated method BigInteger::testBit() has been removed, use isBitSet() instead
• deprecated method BigInteger::gcdMultiple() has been removed, use gcdAll() instead
• deprecated method BigDecimal::exactlyDividedBy() has been removed, use dividedByExact() instead
• deprecated method BigDecimal::getIntegralPart() has been removed (will be re-introduced as returning BigInteger in 0.16)
• deprecated method BigDecimal::getFractionalPart() has been removed (will be re-introduced as returning BigDecimal with a different meaning in 0.16)
• deprecated method BigDecimal::stripTrailingZeros() has been removed, use strippedOfTrailingZeros() instead
• deprecated method BigRational::nd() has been removed, use ofFraction() instead
• deprecated method BigRational::quotient() has been removed, use getIntegralPart() instead
• deprecated method BigRational::remainder() has been removed, use $number->getNumerator()->remainder($number->getDenominator()) instead
• deprecated method BigRational::quotientAndRemainder() has been removed, use $number->getNumerator()->quotientAndRemainder($number->getDenominator()) instead
• deprecated RoundingMode upper snake case constants (e.g. HALF_UP) have been removed, use the pascal case version (e.g. HalfUp) instead

The following breaking changes only affect you if you're using named arguments:

• BigInteger::mod() now uses $modulus as the parameter name
• BigInteger::modInverse() now uses $modulus as the parameter name
• BigInteger::modPow() now uses $exponent and $modulus as parameter names
• BigInteger::shiftedLeft() now uses $bits as the parameter name
• BigInteger::shiftedRight() now uses $bits as the parameter name
• BigInteger::isBitSet() now uses $bitIndex as the parameter name
• BigInteger::randomBits() now uses $bitCount as the parameter name
• BigDecimal::withPointMovedLeft() now uses $places as the parameter name
• BigDecimal::withPointMovedRight() now uses $places as the parameter name

The following breaking changes are unlikely to affect you:

• DivisionByZeroException::modulusMustNotBeZero() has been renamed to zeroModulus()
• DivisionByZeroException::denominatorMustNotBeZero() has been renamed to zeroDenominator()
• IntegerOverflowException::toIntOverflow() has been renamed to integerOutOfRange()
• RoundingNecessaryException::roundingNecessary() has been removed

🗑️ Deprecations

• Method BigRational::simplified() is deprecated, as it is now a no-op

✨ New features

• BigInteger::power(), BigDecimal::power() and BigRational::power() no longer enforce an exponent limit
• BigInteger::shiftedLeft() and BigInteger::shiftedRight() no longer enforce a limit on the number of bits
• BigRational::power() now accepts negative exponents
• New exception: InvalidArgumentException for invalid argument errors
• New exception: NoInverseException for modular inverse errors
• New exception: RandomSourceException for random source errors

👌 Improvements

• Narrowed parameter and return types with static analysis annotations (#108 by @simPod)

🗑️ Deprecations

• Method BigInteger::testBit() is deprecated, use isBitSet() instead

✨ New features

• New method: BigInteger::isBitSet() (replaces testBit())
• New method: BigNumber::toString() (alias of magic method __toString())

👌 Improvements

• Performance optimization of BigRational comparison methods
• More exceptions have been documented with @throws annotations

✨ New features

• clamp() is now available on the base BigNumber class

👌 Improvements

• Improved @throws exception documentation

🗑️ Deprecations

• Not passing a $scale to BigDecimal::dividedBy() is deprecated; $scale will be required in 0.15

👌 Improvements

• BigRational::toFloat() never returns NAN anymore

🗑️ Deprecations

• Not passing a rounding mode to BigInteger::sqrt() and BigDecimal::sqrt() triggers a deprecation notice: the default rounding mode will change from Down to Unnecessary in 0.15

✨ New features

• BigInteger::sqrt() and BigDecimal::sqrt() now support rounding
• abs() and negated() methods are now available on the base BigNumber class

👌 Improvements

• Alphabet is now checked for duplicate characters in BigInteger::(from|to)ArbitraryBase()
• BigNumber::ofNullable() is now marked as @pure

🗑️ Deprecations

• Passing a negative modulus to BigInteger::mod() is deprecated to align with Euclidean modulo semantics; it will throw InvalidArgumentException in 0.15
• Method BigDecimal::stripTrailingZeros() is deprecated, use strippedOfTrailingZeros() instead

✨ New features

• BigInteger::modPow() now accepts negative bases
• New method: BigDecimal::strippedOfTrailingZeros() (replaces stripTrailingZeros())

👌 Improvements

• clamp() methods are now marked as @pure

✨ New features

• New method: BigInteger::lcm()
• New method: BigInteger::lcmAll()
• New method: BigRational::toRepeatingDecimalString()

🐛 Bug fixes

• BigInteger::gcdAll() / gcdMultiple() could return a negative result when used with a single negative number

🗑️ Deprecations

• Passing float values to of() or arithmetic methods is deprecated and will be removed in 0.15; cast to string explicitly to preserve the previous behaviour (#105)
• Accessing RoundingMode enum cases through upper snake case (e.g. HALF_UP) is deprecated, use the pascal case version (e.g. HalfUp) instead
• Method BigInteger::gcdMultiple() is deprecated, use gcdAll() instead
• Method BigDecimal::exactlyDividedBy() is deprecated, use dividedByExact() instead
• Method BigDecimal::getIntegralPart() is deprecated (will be removed in 0.15, and re-introduced as returning BigInteger in 0.16)
• Method BigDecimal::getFractionalPart() is deprecated (will be removed in 0.15, and re-introduced as returning BigDecimal with a different meaning in 0.16)
• Method BigRational::nd() is deprecated, use ofFraction() instead
• Method BigRational::quotient() is deprecated, use getIntegralPart() instead
• Method BigRational::remainder() is deprecated, use $number->getNumerator()->remainder($number->getDenominator()) instead
• Method BigRational::quotientAndRemainder() is deprecated, use $number->getNumerator()->quotientAndRemainder($number->getDenominator()) instead

✨ New features

• New method: BigInteger::gcdAll() (replaces gcdMultiple())
• New method: BigRational::clamp()
• New method: BigRational::ofFraction() (replaces nd())
• New method: BigRational::getIntegralPart() (replaces quotient())
• New method: BigRational::getFractionalPart()

👌 Improvements

• All exceptions thrown by the library now implement a common MathException interface
• BigInteger::modInverse() now accepts BigNumber|int|float|string instead of just BigInteger
• BigInteger::gcdMultiple() now accepts BigNumber|int|float|string instead of just BigInteger

🐛 Bug fixes

• BigInteger::clamp() and BigDecimal::clamp() now throw an exception on inverted bounds, instead of returning an incorrect result

✨ New features

• New method: BigNumber::ofNullable() (#94 by @mrkh995)

✨ Compatibility fixes

• Fixed warnings on PHP 8.5 (#101 and #102 by @julien-boudry)

✨ New features

• New methods: BigInteger::clamp() and BigDecimal::clamp() (#96 by @JesterIruka)

✨ Improvements

• All pure methods in BigNumber classes are now marked as @pure for better static analysis

💥 Breaking changes

• Minimum PHP version is now 8.2
• BigNumber classes are now readonly
• BigNumber is now marked as sealed: it must not be extended outside of this package
• Exception classes are now final

✨ Improvements

• __toString() methods of BigInteger and BigDecimal are now type-hinted as returning numeric-string instead of string (#90 by @vudaltsov)

💥 Breaking changes

• BigDecimal::ofUnscaledValue() no longer throws an exception if the scale is negative
• MathException now extends RuntimeException instead of Exception; this reverts the change introduced in version 0.11.0 (#82)

✨ New features

• BigDecimal::ofUnscaledValue() allows a negative scale (and converts the values to create a zero scale number)

✨ New features

• BigDecimal::getPrecision() Returns the number of significant digits in a decimal number

⚡️ Performance improvements

• Division in NativeCalculator is now faster for small divisors, thanks to @Izumi-kun in #87.

👌 Improvements

• Add missing RoundingNecessaryException to the @throws annotation of BigNumber::of()

⚡️ Performance improvements

• BigNumber::of() is now faster, thanks to @SebastienDug in #77.

💥 Breaking changes

• Minimum PHP version is now 8.1
• RoundingMode is now an enum; if you're type-hinting rounding modes, you need to type-hint against RoundingMode instead of int now
• BigNumber classes do not implement the Serializable interface anymore (they use the new custom object serialization mechanism)
• The following breaking changes only affect you if you're creating your own BigNumber subclasses:
  • the return type of BigNumber::of() is now static
  • BigNumber has a new abstract method from()
  • all public and protected functions of BigNumber are now final

💥 Breaking changes

• Minimum PHP version is now 8.0
• Methods accepting a union of types are now strongly typed^*
• MathException now extends Exception instead of RuntimeException

^{* You may now run into type errors if you were passing Stringable objects to of() or any of the methods internally calling of(), with strict_types enabled. You can fix this by casting Stringable objects to string first.}

👌 Improvements

• BigRational::toFloat() now simplifies the fraction before performing division (#73) thanks to @olsavmic

✨ New features

• BigInteger::gcdMultiple() returns the GCD of multiple BigInteger numbers

💥 Breaking changes

• Minimum PHP version is now 7.4

🚀 Compatibility with PHP 8.1

• Support for custom object serialization; this removes a warning on PHP 8.1 due to the Serializable interface being deprecated (#60) thanks @TRowbotham

🐛 Bug fix

• Incorrect results could be returned when using the BCMath calculator, with a default scale set with bcscale(), on PHP >= 7.2 (#55).

✨ New features

• BigInteger::not() returns the bitwise NOT value

🐛 Bug fixes

• BigInteger::toBytes() could return an incorrect binary representation for some numbers
• The bitwise operations and(), or(), xor() on BigInteger could return an incorrect result when the GMP extension is not available

👌 Improvements

• BigNumber::of() now accepts .123 and 123. formats, both of which return a BigDecimal

💥 Breaking changes

• Deprecated method BigInteger::powerMod() has been removed - use modPow() instead
• Deprecated method BigInteger::parse() has been removed - use fromBase() instead

🐛 Bug fix

• BigInteger::toBytes() could return an incorrect binary representation for some numbers
• The bitwise operations and(), or(), xor() on BigInteger could return an incorrect result when the GMP extension is not available

🚑 Critical fix

• This version reintroduces the deprecated BigInteger::parse() method, that has been removed by mistake in version 0.8.9 and should have lasted for the whole 0.8 release cycle.

✨ New features

• BigInteger::modInverse() calculates a modular multiplicative inverse
• BigInteger::fromBytes() creates a BigInteger from a byte string
• BigInteger::toBytes() converts a BigInteger to a byte string
• BigInteger::randomBits() creates a pseudo-random BigInteger of a given bit length
• BigInteger::randomRange() creates a pseudo-random BigInteger between two bounds

💩 Deprecations

• BigInteger::powerMod() is now deprecated in favour of modPow()

🐛 Fixes

• added missing ext-json requirement, due to BigNumber implementing JsonSerializable

⚡️ Optimizations

• additional optimization in BigInteger::remainder()

✨ New features

• BigInteger::getLowestSetBit() returns the index of the rightmost one bit

✨ New features

• BigInteger::isEven() tests whether the number is even
• BigInteger::isOdd() tests whether the number is odd
• BigInteger::testBit() tests if a bit is set
• BigInteger::getBitLength() returns the number of bits in the minimal representation of the number

🛠️ Maintenance release

Classes are now annotated for better static analysis with psalm.

This is a maintenance release: no bug fixes, no new features, no breaking changes.

✨ New feature

BigInteger::powerMod() performs a power-with-modulo operation. Useful for crypto.

✨ New feature

BigInteger::mod() returns the modulo of two numbers. The modulo differs from the remainder when the signs of the operands are different.

⚡️ Performance improvements

A few additional optimizations in BigInteger and BigDecimal when one of the operands can be returned as is. Thanks to @tomtomsen in #24.

🐛 Bug fixes

• BigInteger::toBase() could return an empty string for zero values (BCMath & Native calculators only, GMP calculator unaffected)

✨ New features

• BigInteger::toArbitraryBase() converts a number to an arbitrary base, using a custom alphabet
• BigInteger::fromArbitraryBase() converts a string in an arbitrary base, using a custom alphabet, back to a number

These methods can be used as the foundation to convert strings between different bases/alphabets, using BigInteger as an intermediate representation.

💩 Deprecations

• BigInteger::parse() is now deprecated in favour of fromBase()

BigInteger::fromBase() works the same way as parse(), with 2 minor differences:

• the $base parameter is required, it does not default to 10
• it throws a NumberFormatException instead of an InvalidArgumentException when the number is malformed

Improvements

• Safer conversion from float when using custom locales
• Much faster NativeCalculator implementation 🚀

You can expect at least a 3x performance improvement for common arithmetic operations when using the library on systems without GMP or BCMath; it gets exponentially faster on multiplications with a high number of digits. This is due to calculations now being performed on whole blocks of digits (the block size depending on the platform, 32-bit or 64-bit) instead of digit-by-digit as before.

New method

BigNumber::sum() returns the sum of one or more numbers.

Bug fix: of() factory methods could fail when passing a float in environments using a LC_NUMERIC locale with a decimal separator other than '.' (#20).

Thanks @manowark 👍

New method

BigDecimal::sqrt() calculates the square root of a decimal number, to a given scale.

New method

BigInteger::sqrt() calculates the square root of a number (thanks @peter279k).

New exception

NegativeNumberException is thrown when calling sqrt() on a negative number.

Performance update

• Further improvement of toInt() performance
• NativeCalculator can now perform some multiplications more efficiently

Performance optimization of toInt() methods.

Breaking changes

The following deprecated methods have been removed. Use the new method name instead:

Method removed	Replacement method
BigDecimal::getIntegral()	BigDecimal::getIntegralPart()
BigDecimal::getFraction()	BigDecimal::getFractionalPart()

---

New features

BigInteger has been augmented with 5 new methods for bitwise operations:

New method	Description
and()	performs a bitwise AND operation on two numbers
or()	performs a bitwise OR operation on two numbers
xor()	performs a bitwise XOR operation on two numbers
shiftedLeft()	returns the number shifted left by a number of bits
shiftedRight()	returns the number shifted right by a number of bits

Thanks to @DASPRiD 👍

New method: BigDecimal::hasNonZeroFractionalPart()

Renamed/deprecated methods:

• BigDecimal::getIntegral() has been renamed to getIntegralPart() and is now deprecated
• BigDecimal::getFraction() has been renamed to getFractionalPart() and is now deprecated

Performance update

BigInteger::parse() and toBase() now use GMP's built-in base conversion features when available.

This is a maintenance release, no code has been changed.

• When installed with --no-dev, the autoloader does not autoload tests anymore
• Tests and other files unnecessary for production are excluded from the dist package

This will help make installations more compact.

Methods renamed:

• BigNumber:sign() has been renamed to getSign()
• BigDecimal::unscaledValue() has been renamed to getUnscaledValue()
• BigDecimal::scale() has been renamed to getScale()
• BigDecimal::integral() has been renamed to getIntegral()
• BigDecimal::fraction() has been renamed to getFraction()
• BigRational::numerator() has been renamed to getNumerator()
• BigRational::denominator() has been renamed to getDenominator()

Classes renamed:

• ArithmeticException has been renamed to MathException

The base class for all exceptions is now MathException. ArithmeticException has been deprecated, and will be removed in 0.7.0.

A number of methods have been renamed:

• BigNumber:sign() is deprecated; use getSign() instead
• BigDecimal::unscaledValue() is deprecated; use getUnscaledValue() instead
• BigDecimal::scale() is deprecated; use getScale() instead
• BigDecimal::integral() is deprecated; use getIntegral() instead
• BigDecimal::fraction() is deprecated; use getFraction() instead
• BigRational::numerator() is deprecated; use getNumerator() instead
• BigRational::denominator() is deprecated; use getDenominator() instead

The old methods will be removed in version 0.7.0.

• Minimum PHP version is now 7.1; for PHP 5.6 and PHP 7.0 support, use version 0.5
• Deprecated method BigDecimal::withScale() has been removed; use toScale() instead
• Method BigNumber::toInteger() has been renamed to toInt()