Add log2, log10 and log256 functions

CHANGELOG.md

@@ -28,6 +28,7 @@
  * `Arrays`: Add `unsafeAccess` functions that allow reading and writing to an element in a storage array bypassing Solidity's "out-of-bounds" check. ([#3589](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3589))
  * `Strings`: optimize `toString`. ([#3573](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3573))
  * `Ownable2Step`: extension of `Ownable` that makes the ownership transfers a two step process. ([#3620](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3620))
+ * `Math`: Add `log2`, `log10` and `log256`. ([#3670](https://github.com/OpenZeppelin/openzeppelin-contracts/pull/3670))
 
 ### Breaking changes
 

contracts/mocks/MathMock.sol

@@ -33,4 +33,16 @@ contract MathMock {
     function sqrt(uint256 a, Math.Rounding direction) public pure returns (uint256) {
         return Math.sqrt(a, direction);
     }
+
+    function log2(uint256 a, Math.Rounding direction) public pure returns (uint256) {
+        return Math.log2(a, direction);
+    }
+
+    function log10(uint256 a, Math.Rounding direction) public pure returns (uint256) {
+        return Math.log10(a, direction);
+    }
+
+    function log256(uint256 a, Math.Rounding direction) public pure returns (uint256) {
+        return Math.log256(a, direction);
+    }
 }

contracts/utils/Strings.sol

@@ -3,6 +3,8 @@
 
 pragma solidity ^0.8.0;
 
+import "./math/Math.sol";
+
 /**
  * @dev String operations.
  */
@@ -15,39 +17,7 @@ library Strings {
      */
     function toString(uint256 value) internal pure returns (string memory) {
         unchecked {
-            uint256 length = 1;
-
-            // compute log10(value), and add it to length
-            uint256 valueCopy = value;
-            if (valueCopy >= 10**64) {
-                valueCopy /= 10**64;
-                length += 64;
-            }
-            if (valueCopy >= 10**32) {
-                valueCopy /= 10**32;
-                length += 32;
-            }
-            if (valueCopy >= 10**16) {
-                valueCopy /= 10**16;
-                length += 16;
-            }
-            if (valueCopy >= 10**8) {
-                valueCopy /= 10**8;
-                length += 8;
-            }
-            if (valueCopy >= 10**4) {
-                valueCopy /= 10**4;
-                length += 4;
-            }
-            if (valueCopy >= 10**2) {
-                valueCopy /= 10**2;
-                length += 2;
-            }
-            if (valueCopy >= 10**1) {
-                length += 1;
-            }
-            // now, length is log10(value) + 1
-
+            uint256 length = Math.log10(value) + 1;
             string memory buffer = new string(length);
             uint256 ptr;
             /// @solidity memory-safe-assembly
@@ -72,33 +42,7 @@ library Strings {
      */
     function toHexString(uint256 value) internal pure returns (string memory) {
         unchecked {
-            uint256 length = 1;
-
-            // compute log256(value), and add it to length
-            uint256 valueCopy = value;
-            if (valueCopy >= 1 << 128) {
-                valueCopy >>= 128;
-                length += 16;
-            }
-            if (valueCopy >= 1 << 64) {
-                valueCopy >>= 64;
-                length += 8;
-            }
-            if (valueCopy >= 1 << 32) {
-                valueCopy >>= 32;
-                length += 4;
-            }
-            if (valueCopy >= 1 << 16) {
-                valueCopy >>= 16;
-                length += 2;
-            }
-            if (valueCopy >= 1 << 8) {
-                valueCopy >>= 8;
-                length += 1;
-            }
-            // now, length is log256(value) + 1
-
-            return toHexString(value, length);
+            return toHexString(value, Math.log256(value) + 1);
         }
     }
 

contracts/utils/math/Math.sol

@@ -167,35 +167,7 @@ library Math {
         // This gives `2**k < a <= 2**(k+1)` → `2**(k/2) <= sqrt(a) < 2 ** (k/2+1)`.
         // Using an algorithm similar to the msb computation, we are able to compute `result = 2**(k/2)` which is a
         // good first approximation of `sqrt(a)` with at least 1 correct bit.
-        uint256 result = 1;
-        uint256 x = a;
-        if (x >> 128 > 0) {
-            x >>= 128;
-            result <<= 64;
-        }
-        if (x >> 64 > 0) {
-            x >>= 64;
-            result <<= 32;
-        }
-        if (x >> 32 > 0) {
-            x >>= 32;
-            result <<= 16;
-        }
-        if (x >> 16 > 0) {
-            x >>= 16;
-            result <<= 8;
-        }
-        if (x >> 8 > 0) {
-            x >>= 8;
-            result <<= 4;
-        }
-        if (x >> 4 > 0) {
-            x >>= 4;
-            result <<= 2;
-        }
-        if (x >> 2 > 0) {
-            result <<= 1;
-        }
+        uint256 result = 1 << (log2(a) / 2);
 
         // At this point `result` is an estimation with one bit of precision. We know the true value is a uint128,
         // since it is the square root of a uint256. Newton's method converges quadratically (precision doubles at
@@ -223,4 +195,146 @@ library Math {
         }
         return result;
     }
+
+    /**
+     * @dev Return the log in base 2, rounded down, of a positive value.
+     * Returns 0 if given 0.
+     */
+    function log2(uint256 value) internal pure returns (uint256) {
+        uint256 result = 0;
+        if (value >> 128 > 0) {
+            value >>= 128;
+            result += 128;
+        }
+        if (value >> 64 > 0) {
+            value >>= 64;
+            result += 64;
+        }
+        if (value >> 32 > 0) {
+            value >>= 32;
+            result += 32;
+        }
+        if (value >> 16 > 0) {
+            value >>= 16;
+            result += 16;
+        }
+        if (value >> 8 > 0) {
+            value >>= 8;
+            result += 8;
+        }
+        if (value >> 4 > 0) {
+            value >>= 4;
+            result += 4;
+        }
+        if (value >> 2 > 0) {
+            value >>= 2;
+            result += 2;
+        }
+        if (value >> 1 > 0) {
+            result += 1;
+        }
+        return result;
+    }
+
+    /**
+     * @dev 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) {
+        uint256 result = log2(value);
+        if (rounding == Rounding.Up && 1 << result < value) {
+            result += 1;
+        }
+        return result;
+    }
+
+    /**
+     * @dev Return the log in base 10, rounded down, of a positive value.
+     * Returns 0 if given 0.
+     */
+    function log10(uint256 value) internal pure returns (uint256) {
+        uint256 result = 0;
+        if (value >= 10**64) {
+            value /= 10**64;
+            result += 64;
+        }
+        if (value >= 10**32) {
+            value /= 10**32;
+            result += 32;
+        }
+        if (value >= 10**16) {
+            value /= 10**16;
+            result += 16;
+        }
+        if (value >= 10**8) {
+            value /= 10**8;
+            result += 8;
+        }
+        if (value >= 10**4) {
+            value /= 10**4;
+            result += 4;
+        }
+        if (value >= 10**2) {
+            value /= 10**2;
+            result += 2;
+        }
+        if (value >= 10**1) {
+            result += 1;
+        }
+        return result;
+    }
+
+    /**
+     * @dev 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) {
+        uint256 result = log10(value);
+        if (rounding == Rounding.Up && 10**result < value) {
+            result += 1;
+        }
+        return result;
+    }
+
+    /**
+     * @dev Return the log in base 256, rounded down, of a positive value.
+     * 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 value) internal pure returns (uint256) {
+        uint256 result = 0;
+        if (value >> 128 > 0) {
+            value >>= 128;
+            result += 16;
+        }
+        if (value >> 64 > 0) {
+            value >>= 64;
+            result += 8;
+        }
+        if (value >> 32 > 0) {
+            value >>= 32;
+            result += 4;
+        }
+        if (value >> 16 > 0) {
+            value >>= 16;
+            result += 2;
+        }
+        if (value >> 8 > 0) {
+            result += 1;
+        }
+        return result;
+    }
+
+    /**
+     * @dev Return the log in base 10, following the selected rounding direction, of a positive value.
+     * Returns 0 if given 0.
+     */
+    function log256(uint256 value, Rounding rounding) internal pure returns (uint256) {
+        uint256 result = log256(value);
+        if (rounding == Rounding.Up && 1 << (result * 8) < value) {
+            result += 1;
+        }
+        return result;
+    }
 }