Class IntMath
Utility class for arithmetic operations on integers that wraps around upon
overflow.
Important
This class is not intended for use as a way to properly perform arithmetic
operations on integers and should not be used in place of the native
arithmetic operators or any other library designed for such purpose.
Unlike other languages that overflow large positive integers into large
negative integers, PHP actually overflows integers to floating-point
numbers. In most cases, arithmetic overflows must be treated as an unusual
circumstance which requires special handling. However, there are some cases
where such wrap-around behavior is actually useful - for example with TCP
sequence numbers or certain algorithms, such as hash calculation. This
utility class provides basic arithmetic functions that operate in accordance
to that behaviour.
To illustrate, consider the following example:
var_dump(PHP_MAX_INT + 1);
var_dump(IntMath::add(PHP_MAX_INT, 1));
As previously shown, adding one to the largest supported integer using
native arithmetic operators will result in a floating-point number. By
contrast, using IntMath::add() will cause an overflow, resulting
in the smallest integer supported in this build of PHP.
Methods summary
public static
integer
|
#
negate( integer $a )
Returns the negation of the argument.
Returns the negation of the argument.
For integer values, negation is the same as subtraction from zero.
Because PHP uses two's-complement representation for integers and the
range of two's-complement values is not symmetric, the negation of the
maximum negative integer results in that same maximum negative number.
Despite the fact that overflow has occurred, no exception is thrown.
For all integer values $a, -$a equals (~$a) + 1.
Parameters
Returns
integer
The result.
Throws
InvalidArgumentException
If the argument is not an integer.
|
public static
integer
|
#
add( integer $a, integer $b )
Returns the sum of the arguments.
Returns the sum of the arguments.
The result is the low-order bits of the true mathematical result as
represented in a sufficiently wide two's-complement format. If overflow
occurs, then the sign of the result may not be the same as the sign of
the mathematical sum of the two values. Despite the overflow, no
exception is thrown in this case.
Parameters
- $a
- The addend.
- $b
- The addend.
Returns
integer
The sum.
Throws
InvalidArgumentException If one of the arguments is not an
integer.
|
public static
integer
|
#
subtract( integer $a, integer $b )
Returns the difference of the arguments.
Returns the difference of the arguments.
The subtraction of a positive number yields the same result as the
addition of a negative number of equal magnitude. Furthermore, the
subtraction from zero is the same as negation.
The result is the low-order bits of the true mathematical result as
represented in a sufficiently wide two's-complement format. If overflow
occurs, then the sign of the result may not be the same as the sign of
the mathematical difference of the two values. Despite the overflow, no
exception is thrown in this case.
Parameters
- $a
- The minuend.
- $b
- The subtrahend.
Returns
integer
The difference.
Throws
InvalidArgumentException If one of the arguments is not an
integer.
|
public static
integer
|
#
multiply( integer $a, integer $b )
Returns the product of the arguments.
Returns the product of the arguments.
The result is the low-order bits of the true mathematical result as
represented in a sufficiently wide two's-complement format. If overflow
occurs, then the sign of the result may not be the same as the sign of
the mathematical product of the two values. Despite the overflow, no
exception is thrown in this case.
Parameters
- $a
- The multiplicand.
- $b
- The multiplier.
Returns
integer
The product.
Throws
InvalidArgumentException If one of the arguments is not an
integer.
|
public static
integer
|
#
divide( integer $a, integer $b )
Returns the quotient of the arguments.
Returns the quotient of the arguments.
The division rounds the result towards zero. Thus the absolute value of
the result is the largest possible integer that is less than or equal to
the absolute value of the quotient of the two operands. The result is
zero or positive when the two operands have the same sign and zero or
negative when the two operands have opposite signs.
There is one special case that does not satisfy this rule: if the
dividend is the negative integer of largest possible magnitude for its
type, and the divisor is -1, then integer overflow occurs and the
result is equal to the dividend. Despite the overflow, no exception is
thrown in this case. On the other hand if the value of the divisor in an
integer division is 0, then a DivisionByZeroException is thrown.
Parameters
- $a
- The dividend.
- $b
- The divisor.
Returns
integer
The quotient.
Throws
|
Constants summary
integer |
MAX_INT
The largest supported integer
The largest supported integer
|
|
|
MIN_INT
The smallest supported integer
The smallest supported integer
|
|