Unsafe Math for Solidity 0.8+
This library and custom user types allow for the use of unchecked math operations when appropriate. Gas savings can be realized when it is already known that the results will not overflow.
Install
npm install -D @0xdoublesharp/unsafe-math
yarn add -D @0xdoublesharp/unsafe-math
UnsafeMath
Library The UnsafeMath
library provides unchecked math operations for uint256
and int256
types with Solidity 0.8.0+. It also provides interoperability and conversion for the U256
and I256
user defined types.
uint256
Type Use the UnsafeMath
library for uint256
types to perform unchecked math operations on two unsigned integers.
API
using UnsafeMath for uint256;
-
Math
-
_uint256.add(uint256 _addend)
: add a uint256 to a uint256 -
_uint256.sub(uint256 _subtrahend)
: subtract a uint256 from a uint256 -
_uint256.inc()
: increment a uint256 -
_uint256.dec()
: decrement a uint256 -
_uint256.mul(uint256 _multiplier)
: multiply a uint256 by a uint256 -
_uint256.div(uint256 _divisor)
: divide a uint256 from a uint256 -
_uint256.mod(uint256 _divisor)
: get the modulus of uint256s -
_uint256.exp(uint256 _exponent)
: raise a uint256 by an exponent
-
Example
import { UnsafeMath } from '@0xdoublesharp/unsafe-math/contracts/UnsafeMath.sol';
contract ContractA {
using UnsafeMath for uint256;
function add(uint256 a, uint256 b) external pure returns (uint256) {
return a.add(b);
}
function while(uint256 times) external pure {
uint256 _iter = times;
while (_iter != 0) {
_iter = _iter.dec();
int64 _int64 = int64(_iter);
// ...
}
}
function for(uint256 times) external pure {
for (uint256 _iter; _iter < times; _iter = _iter.inc()) {
int64 _int64 = int64(_iter);
// ...
}
}
}
int256
Type Use the UnsafeMath
library for int256
types to perform unchecked math operations on two signed integers. Note that exp()
is not available for signed integers.
API
using UnsafeMath for int256;
-
Math
-
_int256.add(int256 _addend)
: add an int256 to an int256 -
_int256.sub(int256 _subtrahend)
: subtract an int256 from an int256 -
_int256.inc()
: increment an int256 value -
_int256.dec()
: decrement an int256 -
_int256.mul(int256 _multiplier)
: multiply an int256 by an int256 -
_int256.div(int256 _divisor)
: divide an int256 from an int256 -
_int256.mod(int256 _divisor)
: get the modulus of int256s
-
Example
import { UnsafeMath } from '@0xdoublesharp/unsafe-math/contracts/UnsafeMath.sol';
contract ContractB {
using UnsafeMath for int256;
function sub(int256 a, int256 b) external pure returns (int256) {
return a.sub(b);
}
}
U256
User Defined Type Used with U256
to access helper methods for interacting with uint256
types and functionality not available in overloaded operators, such as bit shifting and exponential operations.
API
using UnsafeMath for U256;
-
Math
-
_U256.add(uint256 _addend)
: add a U256 to a uint256 -
_U256.sub(uint256 _subtrahend)
: subtract a U256 from a uint256 -
_U256.inc()
: increment a U256 -
_U256.dec()
: decrement a U256 -
_U256.mul(uint256 _multiplier)
: multiply a U256 by a uint256 -
_U256.div(uint256 _divisor)
: divide a uint256 from a U256 -
_U256.mod(uint256 _divisor)
: get the modulus of U256 and uint256 -
_U256.exp(uint256 _exponent)
: raise a U256 by an exponent
-
-
Comparison
-
_U256.eq(uint256 _compare)
: compare U256 and uint256 equality -
_U256.neq(uint256 _compare)
: compare U256 and uint256 non-equality -
_U256.lt(uint256 _compare)
: compare U256 and uint256 less than uint256 -
_U256.lte(uint256 _compare)
: compare U256 less than or equal to uint256 -
_U256.gt(uint256 _compare
: compare U256 greater than uint256 -
_U256.gte(uint256 _compare)
: compare U256 greater than or equal to uint256
-
-
Logical
-
_U256.and(uint256 _operator)
: bitwise AND on U256 and uint256 -
_U256.or(uint256 _operator)
: bitwise OR on U256 and uint256 -
_U256.xor(uint256 _operator)
: bitwise XOR on U256 and uint256 -
_U256.not()
: bitwise NOT on U256 -
_U256.rshift(U256 _shift)
: right shift U256 by U256 -
_U256.lshift(U256 _shift)
: right shift U256 by U256 -
_U256.rshift(uint256 _shift)
: right shift U256 by uint256 -
_U256.lshift(uint256 _shift)
: right shift U256 by uint256
-
-
As Unsigned Integer
-
_U256.asUint8()
: U256 to uint8 -
_U256.asUint16()
: U256 to uint16 -
_U256.asUint32()
: U256 to uint32 -
_U256.asUint64()
: U256 to uint64 -
_U256.asUint128()
: U256 to uint128 -
_U256.asUint256()
: U256 to uint256
-
-
As Signed Integer
-
_U256.asInt8()
: U256 to int8 -
_U256.asInt16()
: U256 to int16 -
_U256.asInt32()
: U256 to int32 -
_U256.asInt64()
: U256 to int64 -
_U256.asInt128()
: U256 to int128 -
_U256.asInt256()
: U256 to int256
-
-
As U256
-
_uint256.asU256()
: convert a uint256 to U256 -
_int256.asU256()
: convert an int256 to U256
-
Example
import { UnsafeMath, U256 } from '@0xdoublesharp/unsafe-math/contracts/UnsafeMath.sol';
contract ContractA {
using UnsafeMath for U256;
using UnsafeMath for uint256;
using UnsafeMath for int256;
function add(int256 a, uint256 b) external pure returns (uint256) {
return a.asU256().add(b).asUint256();
}
function sub(uint256 a, uint256 b) external pure returns (uint256) {
return (a.asU256() - b.asU256()).asUint256();
}
}
I256
User Defined Type Use with I256
to access helper methods for interacting with int256
types and functionality not available in overloaded operators.
API
using UnsafeMath for I256;
-
Math
-
_I256.add(uint256 _addend)
: add an I256 to a int256 -
_I256.sub(uint256 _subtrahend)
: subtract an I256 from a int256 -
_I256.inc()
: increment an I256 -
_I256.dec()
: decrement an I256 -
_I256.mul(uint256 _multiplier)
: multiply an I256 by a int256 -
_I256.div(uint256 _divisor)
: divide a int256 from an I256 -
_I256.mod(uint256 _divisor)
: get the modulus of U256 and uint256
-
-
Comparison
-
_I256.eq(uint256 _compare)
: compare U256 and uint256 equality -
_I256.neq(uint256 _compare)
: compare U256 and uint256 non-equality -
_I256.lt(uint256 _compare)
: compare U256 and uint256 less than uint256 -
_I256.lte(uint256 _compare)
: compare U256 less than or equal to uint256 -
_I256.gt(uint256 _compare
: compare U256 greater than uint256 -
_I256.gte(uint256 _compare)
: compare U256 greater than or equal to uint256
-
-
Logical
-
_I256.and(uint256 _operator)
: bitwise AND on U256 and uint256 -
_I256.or(uint256 _operator)
: bitwise OR on U256 and uint256 -
_I256.xor(uint256 _operator)
: bitwise XOR on U256 and uint256 -
_I256.not()
: bitwise NOT on U256
-
-
As Unsigned Integer
-
_I256.asUint8()
: U256 to uint8 -
_I256.asUint16()
: U256 to uint16 -
_I256.asUint32()
: U256 to uint32 -
_I256.asUint64()
: U256 to uint64 -
_I256.asUint128()
: U256 to uint128 -
_I256.asUint256()
: U256 to uint256
-
-
As Signed Integer
-
_I256.asInt8()
: U256 to int8 -
_I256.asInt16()
: U256 to int16 -
_I256.asInt32()
: U256 to int32 -
_I256.asInt64()
: U256 to int64 -
_I256.asInt128()
: U256 to int128 -
_I256.asInt256()
: U256 to int256
-
-
As I256
-
_uint256.asI256()
: convert a int256 to I256 -
_int256.asI256()
: convert an int256 to I256
-
Example
import { UnsafeMath, I256 } from '@0xdoublesharp/unsafe-math/contracts/UnsafeMath.sol';
contract ContractB {
using UnsafeMath for I256;
using UnsafeMath for uint256;
using UnsafeMath for int256;
function add(int256 a, uint256 b) external pure returns (int256) {
I256 _a = a.asI256();
return _a.add(int256(b)).asInt256();
}
function sub(uint256 a, uint256 b) external pure returns (int256) {
I256 _a = a.asI256();
I256 _b = b.asI256();
return (a - b).asInt256();
}
}
U256
and I256
User Defined Types: User defined types with operator overloads are also provided to take advantage of the latest Solidity features. Use U256
for unchecked unsigned integer operations, or I256
for unchecked signed integer operations. Helper methods are also provided for interoperating with uint256
and int256
via the UnsafeMath
library.
The overloads also provide comparison and bitwise operators where available.
U256
User Defined Type The U256
user defined type can perform unchecked math operations using overloaded operators.
API
-
Math
-
_u256 + _u256
: add a U256 to a U256 -
_u256 - _u256
: subtract a U256 from a U256 -
_u256 * _u256
: multiply a U256 by a U256 -
_u256 / _u256
: divide a U256 from a U256 -
_u256 % _u256
: get the modulus of U256s
-
-
Comparison
-
_u256 == _u256
: compare U256 equality -
_u256 != _u256
: compare U256 non-equality -
_u256 < _u256
: compare U256 less than U256 -
_u256 <= _u256
: compare U256 less than or equal to U256 -
_u256 > _u256
: compare U256 greater than U256 -
_u256 >= _u256
: compare U256 greater than or equal to U256
-
-
Logical
-
_u256 & _u256
: bitwise AND on U256 -
_u256 | _u256
: bitwise OR on U256 -
_u256 ^ _u256
: bitwise XOR on U256 -
~_u256
: bitwise NOT on U256
-
Example
import { U256 } from '@0xdoublesharp/unsafe-math/contracts/types/U256.sol';
contract ContractA {
function add(uint256 a, uint256 b) external pure returns (uint256) {
return (U256.wrap(a) - U256.wrap(b)).asUint256();
}
function while(uint256 times) external pure {
U256 _iter = U256.wrap(times);
while (_iter.neq(0)) {
_iter = _iter.dec();
uint256 _uint256 = _iter.asUint256();
int64 _int64 = _iter.asInt64();
// ...
}
}
function for(uint256 times) external pure {
U256 _times = U256.wrap(times);
for (U256 _iter; _iter < _times; _iter = _iter.inc()) {
uint256 _uint256 = _iter.asUint256();
int64 _int64 = _iter.asInt64();
// ...
}
}
}
I256
User Definited Type The I256
user defined type can perform unchecked math operations using overloaded operators.
API
-
Math
-
_i256 + _i256
: add a I256 to a I256 -
_i256 - _i256
: subtract a I256 from a I256 -
_i256 * _i256
: multiply a I256 by a I256 -
_i256 / _i256
: divide a I256 from a I256 -
_i256 % _i256
: get the modulus of I256s
-
-
Comparison
-
_i256 == _i256
: compare I256 equality -
_i256 != _i256
: compare I256 non-equality -
_i256 < _i256
: compare I256 less than I256 -
_i256 <= _i256
: compare I256 less than or equal to I256 -
_i256 > _i256
: compare I256 greater than I256 -
_i256 >= _i256
: compare I256 greater than or equal to I256
-
-
Logical
-
_i256 & _i256
: bitwise AND on I256 -
_i256 | _i256
: bitwise OR on I256 -
_i256 ^ _i256
: bitwise XOR on I256 -
~_i256
: bitwise NOT on I256
-
Example
import { I256 } from '@0xdoublesharp/unsafe-math/contracts/types/I256.sol';
contract ContractB {
function add(int256 a, int256 b) external pure returns (int256) {
return (I256.wrap(a) - I256.wrap(b)).asInt256();
}
}
Gas Usage Optimization Disabled
See GAS_REPORT.