Math Laravel Package

First stable release 🎉

No changes from version 0.20.0.

✨ 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](https://github.com/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](https://github.com/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](https://github.com/throws) annotations

✨ New features

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

👌 Improvements

• Improved [@throws](https://github.com/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](https://github.com/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](https://github.com/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

• 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](https://github.com/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](https://github.com/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: 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

🐛 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

👌 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

🚑 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.