Add toUint, toInt and hexToUint to Strings

.changeset/eighty-hounds-promise.md

@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`Strings`: Add `toUint`, `toInt` and `hexToUint` to parse strings into numbers.

contracts/utils/Strings.sol

@@ -4,6 +4,7 @@
 pragma solidity ^0.8.20;
 
 import {Math} from "./math/Math.sol";
+import {SafeCast} from "./math/SafeCast.sol";
 import {SignedMath} from "./math/SignedMath.sol";
 
 /**
@@ -18,6 +19,11 @@ library Strings {
      */
     error StringsInsufficientHexLength(uint256 value, uint256 length);
 
+    /**
+     * @dev The string being parsed contains characters that are not in scope of the given base.
+     */
+    error StringsInvalidChar(bytes1 chr, uint8 base);
+
     /**
      * @dev Converts a `uint256` to its ASCII `string` decimal representation.
      */
@@ -115,4 +121,89 @@ library Strings {
     function equal(string memory a, string memory b) internal pure returns (bool) {
         return bytes(a).length == bytes(b).length && keccak256(bytes(a)) == keccak256(bytes(b));
     }
+
+    /**
+     * @dev Parse a decimal string and returns the value as a `uint256`.
+     *
+     * This function will revert if:
+     * - the string contains any character that is not in [0-9].
+     * - the result does not fit in a `uint256`.
+     */
+    function toUint(string memory input) internal pure returns (uint256) {
+        bytes memory buffer = bytes(input);
+
+        uint256 result = 0;
+        uint256 bufferLength = buffer.length;
+        for (uint256 i = 0; i < bufferLength; ++i) {
+            result *= 10; // will revert if overflow
+            result += _parseChr(buffer[i], 10);
+        }
+        return result;
+    }
+
+    /**
+     * @dev Parse a decimal string and returns the value as a `int256`.
+     *
+     * This function will revert if:
+     * - the string contains any character (outside the prefix) that is not in [0-9].
+     * - the result does not fit in a `int256`.
+     */
+    function toInt(string memory input) internal pure returns (int256) {
+        bytes memory buffer = bytes(input);
+
+        // check presence of a negative sign.
+        bool isNegative = bytes1(buffer) == 0x2d;
+        int8 factor = isNegative ? int8(-1) : int8(1);
+
+        int256 result = 0;
+        uint256 bufferLength = buffer.length;
+        for (uint256 i = SafeCast.toUint(isNegative); i < bufferLength; ++i) {
+            result *= 10; // will revert if overflow
+            result += factor * int8(_parseChr(buffer[i], 10)); // parseChr is at most 9, it fits into an int8
+        }
+        return result;
+    }
+
+    /**
+     * @dev Parse a hexadecimal string (with or without "0x" prefix), and returns the value as a `uint256`.
+     *
+     * This function will revert if:
+     * - the string contains any character (outside the prefix) that is not in [0-9a-fA-F].
+     * - the result does not fit in a `uint256`.
+     */
+    function hexToUint(string memory input) internal pure returns (uint256) {
+        bytes memory buffer = bytes(input);
+
+        // skip 0x prefix if present
+        uint256 offset = Math.ternary(bytes2(buffer) == 0x3078, 2, 0);
+
+        uint256 result = 0;
+        uint256 bufferLength = buffer.length;
+        for (uint256 i = offset; i < bufferLength; ++i) {
+            result *= 16; // will revert if overflow
+            result += _parseChr(buffer[i], 16);
+        }
+        return result;
+    }
+
+    function _parseChr(bytes1 chr, uint8 base) private pure returns (uint8) {
+        uint8 value = uint8(chr);
+
+        // Try to parse `chr`:
+        // - Case 1: [0-9]
+        // - Case 2: [a-z]
+        // - Case 2: [A-Z]
+        // - otherwise not supported
+        unchecked {
+            if (value > 47 && value < 58) value -= 48;
+            else if (value > 96 && value < 123) value -= 87;
+            else if (value > 64 && value < 91) value -= 55;
+            else revert StringsInvalidChar(chr, base);
+        }
+
+        // check base
+        if (value >= base) revert StringsInvalidChar(chr, base);
+
+        return value;
+    }
 }

test/utils/Strings.t.sol

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+
+import {Strings} from "@openzeppelin/contracts/utils/Strings.sol";
+
+contract StringsTest is Test {
+    using Strings for *;
+
+    function testParse(uint256 value) external {
+        assertEq(value, value.toString().toUint());
+    }
+
+    function testParseSigned(int256 value) external {
+        assertEq(value, value.toStringSigned().toInt());
+    }
+
+    function testParseHex(uint256 value) external {
+        assertEq(value, value.toHexString().hexToUint());
+    }
+
+    function testParseChecksumHex(address value) external {
+        assertEq(value, address(uint160(value.toChecksumHexString().hexToUint())));
+    }
+}

test/utils/Strings.test.js

@@ -1,6 +1,7 @@
 const { ethers } = require('hardhat');
 const { expect } = require('chai');
 const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
+const { PANIC_CODES } = require('@nomicfoundation/hardhat-chai-matchers/panic');
 
 async function fixture() {
   const mock = await ethers.deployContract('$Strings');
@@ -38,11 +39,13 @@ describe('Strings', function () {
       it('converts MAX_UINT256', async function () {
         const value = ethers.MaxUint256;
         expect(await this.mock.$toString(value)).to.equal(value.toString(10));
+        expect(await this.mock.$toUint(value.toString(10))).to.equal(value);
       });
 
       for (const value of values) {
         it(`converts ${value}`, async function () {
-          expect(await this.mock.$toString(value)).to.equal(value);
+          expect(await this.mock.$toString(value)).to.equal(value.toString(10));
+          expect(await this.mock.$toUint(value.toString(10))).to.equal(value);
         });
       }
     });
@@ -51,39 +54,54 @@ describe('Strings', function () {
       it('converts MAX_INT256', async function () {
         const value = ethers.MaxInt256;
         expect(await this.mock.$toStringSigned(value)).to.equal(value.toString(10));
+        expect(await this.mock.$toInt(value.toString(10))).to.equal(value);
       });
 
       it('converts MIN_INT256', async function () {
         const value = ethers.MinInt256;
         expect(await this.mock.$toStringSigned(value)).to.equal(value.toString(10));
+        expect(await this.mock.$toInt(value.toString(10))).to.equal(value);
       });
 
       for (const value of values) {
         it(`convert ${value}`, async function () {
-          expect(await this.mock.$toStringSigned(value)).to.equal(value);
+          expect(await this.mock.$toStringSigned(value)).to.equal(value.toString(10));
+          expect(await this.mock.$toInt(value.toString(10))).to.equal(value);
         });
 
         it(`convert negative ${value}`, async function () {
           const negated = -value;
           expect(await this.mock.$toStringSigned(negated)).to.equal(negated.toString(10));
+          expect(await this.mock.$toInt(negated.toString(10))).to.equal(negated);
         });
       }
     });
   });
 
   describe('toHexString', function () {
     it('converts 0', async function () {
-      expect(await this.mock.getFunction('$toHexString(uint256)')(0n)).to.equal('0x00');
+      const value = 0n;
+      const string = '0x00';
+
+      expect(await this.mock.getFunction('$toHexString(uint256)')(value)).to.equal(string);
+      expect(await this.mock.getFunction('$hexToUint(string)')(string)).to.equal(value);
     });
 
     it('converts a positive number', async function () {
-      expect(await this.mock.getFunction('$toHexString(uint256)')(0x4132n)).to.equal('0x4132');
+      const value = 0x4132n;
+      const string = '0x4132';
+
+      expect(await this.mock.getFunction('$toHexString(uint256)')(value)).to.equal(string);
+      expect(await this.mock.getFunction('$hexToUint(string)')(string)).to.equal(value);
     });
 
     it('converts MAX_UINT256', async function () {
-      expect(await this.mock.getFunction('$toHexString(uint256)')(ethers.MaxUint256)).to.equal(
-        `0x${ethers.MaxUint256.toString(16)}`,
-      );
+      const value = ethers.MaxUint256;
+      const string = `0x${value.toString(16)}`;
+
+      expect(await this.mock.getFunction('$toHexString(uint256)')(value)).to.equal(string);
+      expect(await this.mock.getFunction('$hexToUint(string)')(string)).to.equal(value);
+      expect(await this.mock.getFunction('$hexToUint(string)')(string.replace(/0x/, ''))).to.equal(value);
     });
   });
 
@@ -97,7 +115,7 @@ describe('Strings', function () {
     it('converts a positive number (short)', async function () {
       const length = 1n;
       await expect(this.mock.getFunction('$toHexString(uint256,uint256)')(0x4132n, length))
-        .to.be.revertedWithCustomError(this.mock, `StringsInsufficientHexLength`)
+        .to.be.revertedWithCustomError(this.mock, 'StringsInsufficientHexLength')
         .withArgs(0x4132, length);
     });
 
@@ -177,4 +195,83 @@ describe('Strings', function () {
       expect(await this.mock.$equal(str1, str2)).to.be.true;
     });
   });
+
+  describe('Edge cases: invalid parsing', function () {
+    const ord = x => `0x${x.charCodeAt(0).toString(16)}`;
+
+    it('toUint overflow', async function () {
+      await expect(this.mock.$toUint((ethers.MaxUint256 + 1n).toString(10))).to.be.revertedWithPanic(
+        PANIC_CODES.ARITHMETIC_OVERFLOW,
+      );
+    });
+
+    it('toUint invalid character', async function () {
+      await expect(this.mock.$toUint('0x1'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('x'), 10);
+      await expect(this.mock.$toUint('1f'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('f'), 10);
+      await expect(this.mock.$toUint('-10'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('-'), 10);
+      await expect(this.mock.$toUint('1.0'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('.'), 10);
+      await expect(this.mock.$toUint('1 000'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord(' '), 10);
+    });
+
+    it('toInt overflow', async function () {
+      await expect(this.mock.$toInt((ethers.MaxInt256 + 1n).toString(10))).to.be.revertedWithPanic(
+        PANIC_CODES.ARITHMETIC_OVERFLOW,
+      );
+      await expect(this.mock.$toInt((ethers.MinInt256 - 1n).toString(10))).to.be.revertedWithPanic(
+        PANIC_CODES.ARITHMETIC_OVERFLOW,
+      );
+    });
+
+    it('toInt invalid character', async function () {
+      await expect(this.mock.$toInt('0x1'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('x'), 10);
+      await expect(this.mock.$toInt('1f'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('f'), 10);
+      await expect(this.mock.$toInt('1.0'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('.'), 10);
+      await expect(this.mock.$toInt('1 000'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord(' '), 10);
+    });
+
+    it('hexToUint overflow', async function () {
+      await expect(this.mock.$hexToUint((ethers.MaxUint256 + 1n).toString(16))).to.be.revertedWithPanic(
+        PANIC_CODES.ARITHMETIC_OVERFLOW,
+      );
+    });
+
+    it('hexToUint invalid character', async function () {
+      await expect(this.mock.$hexToUint('0123456789abcdefg'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('g'), 16);
+      await expect(this.mock.$hexToUint('-1'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('-'), 16);
+      await expect(this.mock.$hexToUint('-f'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('-'), 16);
+      await expect(this.mock.$hexToUint('-0xf'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('-'), 16);
+      await expect(this.mock.$hexToUint('1.0'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord('.'), 16);
+      await expect(this.mock.$hexToUint('1 000'))
+        .to.be.revertedWithCustomError(this.mock, 'StringsInvalidChar')
+        .withArgs(ord(' '), 16);
+    });
+  });
 });