Math

Git Source

Author: Modified from OpenZeppelin (https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/utils/math/Math.sol)

Standard math utilities missing in the Solidity language.

Functions

add512

Return the 512-bit addition of two uint256.
The result is stored in two 256 variables such that sum = high * 2²⁵⁶ + low.

function add512(uint256 a, uint256 b) internal pure returns (uint256 high, uint256 low);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
high	`uint256`
low	`uint256`

mul512

Return the 512-bit multiplication of two uint256.
The result is stored in two 256 variables such that product = high * 2²⁵⁶ + low.

function mul512(uint256 a, uint256 b) internal pure returns (uint256 high, uint256 low);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
high	`uint256`
low	`uint256`

tryAdd

Returns the addition of two unsigned integers, with a success flag (no overflow).

function tryAdd(uint256 a, uint256 b) internal pure returns (bool success, uint256 result);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
success	`bool`
result	`uint256`

trySub

Returns the subtraction of two unsigned integers, with a success flag (no overflow).

function trySub(uint256 a, uint256 b) internal pure returns (bool success, uint256 result);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
success	`bool`
result	`uint256`

tryMul

Returns the multiplication of two unsigned integers, with a success flag (no overflow).

function tryMul(uint256 a, uint256 b) internal pure returns (bool success, uint256 result);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
success	`bool`
result	`uint256`

tryDiv

Returns the division of two unsigned integers, with a success flag (no division by zero).

function tryDiv(uint256 a, uint256 b) internal pure returns (bool success, uint256 result);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
success	`bool`
result	`uint256`

tryMod

Returns the remainder of dividing two unsigned integers, with a success flag (no division by zero).

function tryMod(uint256 a, uint256 b) internal pure returns (bool success, uint256 result);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
success	`bool`
result	`uint256`

saturatingAdd

Unsigned saturating addition, bounds to 2²⁵⁶ - 1 instead of overflowing.

function saturatingAdd(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

saturatingSub

Unsigned saturating subtraction, bounds to zero instead of overflowing.

function saturatingSub(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

saturatingMul

Unsigned saturating multiplication, bounds to 2²⁵⁶ - 1 instead of overflowing.

function saturatingMul(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

ternary

Branchless ternary evaluation for condition ? a : b. Gas costs are constant.
IMPORTANT: This function may reduce bytecode size and consume less gas when used standalone. However, the compiler may optimize Solidity ternary operations (i.e. condition ? a : b) to only compute one branch when needed, making this function more expensive.

function ternary(bool condition, uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
condition	`bool`
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

max

Returns the largest of two numbers.

function max(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

min

Returns the smallest of two numbers.

function min(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

average

Returns the average of two numbers. The result is rounded towards zero.

function average(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

ceilDiv

Returns the ceiling of the division of two numbers.
This differs from standard division with / in that it rounds towards infinity instead of rounding towards zero.

function ceilDiv(uint256 a, uint256 b) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
b	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

mulDiv

Calculates floor(x * y / denominator) with full precision. Throws if result overflows a uint256 or denominator == 0.
Original credit to Remco Bloemen under MIT license (https://xn--2-umb.com/21/muldiv) with further edits by Uniswap Labs also under MIT license.

function mulDiv(uint256 x, uint256 y, uint256 denominator) internal pure returns (uint256 result);

Parameters

Name	Type	Description
x	`uint256`
y	`uint256`
denominator	`uint256`

Returns

Name	Type	Description
result	`uint256`

mulDiv

Calculates x * y / denominator with full precision, following the selected rounding direction.

function mulDiv(uint256 x, uint256 y, uint256 denominator, Rounding rounding) internal pure returns (uint256);

Parameters

Name	Type	Description
x	`uint256`
y	`uint256`
denominator	`uint256`
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`uint256`

mulShr

Calculates floor(x * y >> n) with full precision. Throws if result overflows a uint256.

function mulShr(uint256 x, uint256 y, uint8 n) internal pure returns (uint256 result);

Parameters

Name	Type	Description
x	`uint256`
y	`uint256`
n	`uint8`

Returns

Name	Type	Description
result	`uint256`

mulShr

Calculates x * y >> n with full precision, following the selected rounding direction.

function mulShr(uint256 x, uint256 y, uint8 n, Rounding rounding) internal pure returns (uint256);

Parameters

Name	Type	Description
x	`uint256`
y	`uint256`
n	`uint8`
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`uint256`

invMod

Calculate the modular multiplicative inverse of a number in Z/nZ.
If n is a prime, then Z/nZ is a field. In that case all elements are inversible, except 0. If n is not a prime, then Z/nZ is not a field, and some elements might not be inversible.
If the input value is not inversible, 0 is returned.
NOTE: If you know for sure that n is (big) a prime, it may be cheaper to use Fermat's little theorem and get the inverse using Math.modExp(a, n - 2, n). See invModPrime.

function invMod(uint256 a, uint256 n) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
n	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

invModPrime

Variant of invMod. More efficient, but only works if p is known to be a prime greater than 2.
From https://en.wikipedia.org/wiki/Fermat%27s_little_theorem[Fermat's little theorem], we know that if p is prime, then a**(p-1) ≡ 1 mod p. As a consequence, we have a * a**(p-2) ≡ 1 mod p, which means that a**(p-2) is the modular multiplicative inverse of a in Fp.
NOTE: this function does NOT check that p is a prime greater than 2.

function invModPrime(uint256 a, uint256 p) internal view returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
p	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

modExp

Returns the modular exponentiation of the specified base, exponent and modulus (b ** e % m)
Requirements:

modulus can't be zero

underlying staticcall to precompile must succeed

IMPORTANT: The result is only valid if the underlying call succeeds. When using this function, make sure the chain you're using it on supports the precompiled contract for modular exponentiation at address 0x05 as specified in https://eips.ethereum.org/EIPS/eip-198[EIP-198]. Otherwise, the underlying function will succeed given the lack of a revert, but the result may be incorrectly interpreted as 0.

function modExp(uint256 b, uint256 e, uint256 m) internal view returns (uint256);

Parameters

Name	Type	Description
b	`uint256`
e	`uint256`
m	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

tryModExp

Returns the modular exponentiation of the specified base, exponent and modulus (b ** e % m). It includes a success flag indicating if the operation succeeded. Operation will be marked as failed if trying to operate modulo 0 or if the underlying precompile reverted.
IMPORTANT: The result is only valid if the success flag is true. When using this function, make sure the chain you're using it on supports the precompiled contract for modular exponentiation at address 0x05 as specified in https://eips.ethereum.org/EIPS/eip-198[EIP-198]. Otherwise, the underlying function will succeed given the lack of a revert, but the result may be incorrectly interpreted as 0.

function tryModExp(uint256 b, uint256 e, uint256 m) internal view returns (bool success, uint256 result);

Parameters

Name	Type	Description
b	`uint256`
e	`uint256`
m	`uint256`

Returns

Name	Type	Description
success	`bool`
result	`uint256`

modExp

Variant of modExp that supports inputs of arbitrary length.

function modExp(bytes memory b, bytes memory e, bytes memory m) internal view returns (bytes memory);

Parameters

Name	Type	Description
b	`bytes`
e	`bytes`
m	`bytes`

Returns

Name	Type	Description
<none>	`bytes`

tryModExp

Variant of tryModExp that supports inputs of arbitrary length.

function tryModExp(bytes memory b, bytes memory e, bytes memory m)
        internal
        view
        returns (bool success, bytes memory result);

Parameters

Name	Type	Description
b	`bytes`
e	`bytes`
m	`bytes`

Returns

Name	Type	Description
success	`bool`
result	`bytes`

_zeroBytes

Returns whether the provided byte array is zero.

function _zeroBytes(bytes memory buffer) private pure returns (bool);

Parameters

Name	Type	Description
buffer	`bytes`

Returns

Name	Type	Description
<none>	`bool`

sqrt

Returns the square root of a number. If the number is not a perfect square, the value is rounded towards zero.
This method is based on Newton's method for computing square roots; the algorithm is restricted to only using integer operations.

function sqrt(uint256 a) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

sqrt

Calculates sqrt(a), following the selected rounding direction.

function sqrt(uint256 a, Rounding rounding) internal pure returns (uint256);

Parameters

Name	Type	Description
a	`uint256`
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`uint256`

log2

Return the log in base 2 of a positive value rounded towards zero. Returns 0 if given 0.

function log2(uint256 x) internal pure returns (uint256 r);

Parameters

Name	Type	Description
x	`uint256`

Returns

Name	Type	Description
r	`uint256`

log2

Return the log in base 2, following the selected rounding direction, of a positive value. Returns 0 if given 0.

function log2(uint256 value, Rounding rounding) internal pure returns (uint256);

Parameters

Name	Type	Description
value	`uint256`
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`uint256`

log10

Return the log in base 10 of a positive value rounded towards zero. Returns 0 if given 0.

function log10(uint256 value) internal pure returns (uint256);

Parameters

Name	Type	Description
value	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

log10

Return the log in base 10, following the selected rounding direction, of a positive value. Returns 0 if given 0.

function log10(uint256 value, Rounding rounding) internal pure returns (uint256);

Parameters

Name	Type	Description
value	`uint256`
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`uint256`

log256

Return the log in base 256 of a positive value rounded towards zero. Returns 0 if given 0.
Adding one to the result gives the number of pairs of hex symbols needed to represent value as a hex string.

function log256(uint256 x) internal pure returns (uint256 r);

Parameters

Name	Type	Description
x	`uint256`

Returns

Name	Type	Description
r	`uint256`

log256

Return the log in base 256, following the selected rounding direction, of a positive value. Returns 0 if given 0.

function log256(uint256 value, Rounding rounding) internal pure returns (uint256);

Parameters

Name	Type	Description
value	`uint256`
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`uint256`

unsignedRoundsUp

Returns whether a provided rounding mode is considered rounding up for unsigned integers.

function unsignedRoundsUp(Rounding rounding) internal pure returns (bool);

Parameters

Name	Type	Description
rounding	`Rounding`

Returns

Name	Type	Description
<none>	`bool`

clz

Counts the number of leading zero bits in a uint256.

function clz(uint256 x) internal pure returns (uint256);

Parameters

Name	Type	Description
x	`uint256`

Returns

Name	Type	Description
<none>	`uint256`

Enums

Rounding

enum Rounding {
        Floor, // Toward negative infinity
        Ceil, // Toward positive infinity
        Trunc, // Toward zero
        Expand // Away from zero
    }

Variants

Name	Description
Floor
Ceil
Trunc
Expand