Extend Checkpoints with new sizes and lookup mechanisms

contracts/mocks/CheckpointsMock.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/CheckpointsMock.js`.
+// This file was procedurally generated from scripts/generate/templates/CheckpointsMock.js.
 
 pragma solidity ^0.8.0;
 

contracts/mocks/EnumerableMapMock.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/EnumerableMapMock.js`.
+// This file was procedurally generated from scripts/generate/templates/EnumerableMapMock.js.
 
 pragma solidity ^0.8.0;
 

contracts/mocks/EnumerableSetMock.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/EnumerableSetMock.js`.
+// This file was procedurally generated from scripts/generate/templates/EnumerableSetMock.js.
 
 pragma solidity ^0.8.0;
 

contracts/mocks/SafeCastMock.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/SafeCastMock.js`.
+// This file was procedurally generated from scripts/generate/templates/SafeCastMock.js.
 
 pragma solidity ^0.8.0;
 

contracts/utils/Arrays.sol

@@ -52,7 +52,7 @@ library Arrays {
     /**
      * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
      *
-     * WARNING: only use if you are certain pos is lower than the array length.
+     * WARNING: Only use if you are certain `pos` is lower than the array length.
      */
     function unsafeAccess(address[] storage arr, uint256 pos) internal pure returns (StorageSlot.AddressSlot storage) {
         bytes32 slot;
@@ -67,7 +67,7 @@ library Arrays {
     /**
      * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
      *
-     * WARNING: only use if you are certain pos is lower than the array length.
+     * WARNING: Only use if you are certain `pos` is lower than the array length.
      */
     function unsafeAccess(bytes32[] storage arr, uint256 pos) internal pure returns (StorageSlot.Bytes32Slot storage) {
         bytes32 slot;
@@ -82,7 +82,7 @@ library Arrays {
     /**
      * @dev Access an array in an "unsafe" way. Skips solidity "index-out-of-range" check.
      *
-     * WARNING: only use if you are certain pos is lower than the array length.
+     * WARNING: Only use if you are certain `pos` is lower than the array length.
      */
     function unsafeAccess(uint256[] storage arr, uint256 pos) internal pure returns (StorageSlot.Uint256Slot storage) {
         bytes32 slot;

contracts/utils/Checkpoints.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/Checkpoints.js`.
 // OpenZeppelin Contracts (last updated v4.5.0) (utils/Checkpoints.sol)
+// This file was procedurally generated from scripts/generate/templates/Checkpoints.js.
 
 pragma solidity ^0.8.0;
 
@@ -69,6 +69,9 @@ library Checkpoints {
         return push(self, op(latest(self), delta));
     }
 
+    /**
+     * @dev Pushes a (`key`, `value`) pair into a ordered list of checkpoints, either by inserting a new checkpoint, or by updating the last one.
+     */
     function _insert(
         Checkpoint[] storage self,
         uint32 key,
@@ -77,10 +80,10 @@ library Checkpoints {
         uint256 pos = self.length;
 
         if (pos > 0) {
-            // Use of memory is important here.
+            // Copying to memory is important here.
             Checkpoint memory last = _unsafeAccess(self, pos - 1);
 
-            // Checkpoints keys must be increassing.
+            // Checkpoints keys must be increasing.
             require(last._blockNumber <= key, "Checkpoint: invalid key");
 
             // Update or push new checkpoint
@@ -96,6 +99,12 @@ library Checkpoints {
         }
     }
 
+    /**
+     * @dev Return the index of the last checkpoint for which `key` >= checkpoint.key, i.e. the most recent checkpoint which key is lower or equal than the search key.
+     * `low` and `high` define a section where to do the search, with an `low` inclusive and `high` exclusive.
+     *
+     * WARNING: `high` should not be greater than the array's length.
+     */
     function _upperBinaryLookup(
         Checkpoint[] storage self,
         uint32 key,
@@ -113,6 +122,12 @@ library Checkpoints {
         return high;
     }
 
+    /**
+     * @dev Return the index of the first checkpoint for which `key` <= checkpoint.key, i.e. the oldest checkpoint which key is higher or equal than the search key.
+     * `low` and `high` define a section where to do the search, with an `low` inclusive and `high` exclusive.
+     *
+     * WARNING: `high` should not be greater than the array's length.
+     */
     function _lowerBinaryLookup(
         Checkpoint[] storage self,
         uint32 key,
@@ -146,11 +161,19 @@ library Checkpoints {
         uint224 _value;
     }
 
+    /**
+     * @dev Returns the value in the latest checkpoint, or zero if there are no checkpoints.
+     */
     function latest(Trace224 storage self) internal view returns (uint224) {
         uint256 pos = self._checkpoints.length;
         return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
     }
 
+    /**
+     * @dev Pushes a (`key`, `value`) pair into a History so that it is stored as the checkpoint.
+     *
+     * Returns previous value and new value.
+     */
     function push(
         Trace224 storage self,
         uint32 key,
@@ -159,18 +182,27 @@ library Checkpoints {
         return _insert(self._checkpoints, key, value);
     }
 
+    /**
+     * @dev Return the value most recent checkpoint which key is lower or equal than the search key.
+     */
     function lowerLookup(Trace224 storage self, uint32 key) internal view returns (uint224) {
         uint256 length = self._checkpoints.length;
         uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, length);
         return pos == length ? 0 : _unsafeAccess(self._checkpoints, pos)._value;
     }
 
+    /**
+     * @dev Return the value oldest checkpoint which key is higher or equal than the search key.
+     */
     function upperLookup(Trace224 storage self, uint32 key) internal view returns (uint224) {
         uint256 length = self._checkpoints.length;
         uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, length);
         return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
     }
 
+    /**
+     * @dev Return the value oldest checkpoint which key is higher or equal than the search key (similarly to {upperLookupRecent}) doing an exponential lookup first to optimize for recent checkpoints.
+     */
     function upperLookupRecent(Trace224 storage self, uint32 key) internal view returns (uint224) {
         uint256 length = self._checkpoints.length;
         uint256 offset = 1;
@@ -186,6 +218,9 @@ library Checkpoints {
         return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
     }
 
+    /**
+     * @dev Pushes a (`key`, `value`) pair into a ordered list of checkpoints, either by inserting a new checkpoint, or by updating the last one.
+     */
     function _insert(
         Checkpoint224[] storage self,
         uint32 key,
@@ -194,10 +229,10 @@ library Checkpoints {
         uint256 pos = self.length;
 
         if (pos > 0) {
-            // Use of memory is important here.
+            // Copying to memory is important here.
             Checkpoint224 memory last = _unsafeAccess(self, pos - 1);
 
-            // Checkpoints keys must be increassing.
+            // Checkpoints keys must be increasing.
             require(last._key <= key, "Checkpoint: invalid key");
 
             // Update or push new checkpoint
@@ -213,6 +248,12 @@ library Checkpoints {
         }
     }
 
+    /**
+     * @dev Return the index of the last checkpoint for which `key` >= checkpoint.key, i.e. the most recent checkpoint which key is lower or equal than the search key.
+     * `low` and `high` define a section where to do the search, with an `low` inclusive and `high` exclusive.
+     *
+     * WARNING: `high` should not be greater than the array's length.
+     */
     function _upperBinaryLookup(
         Checkpoint224[] storage self,
         uint32 key,
@@ -230,6 +271,12 @@ library Checkpoints {
         return high;
     }
 
+    /**
+     * @dev Return the index of the first checkpoint for which `key` <= checkpoint.key, i.e. the oldest checkpoint which key is higher or equal than the search key.
+     * `low` and `high` define a section where to do the search, with an `low` inclusive and `high` exclusive.
+     *
+     * WARNING: `high` should not be greater than the array's length.
+     */
     function _lowerBinaryLookup(
         Checkpoint224[] storage self,
         uint32 key,
@@ -267,11 +314,19 @@ library Checkpoints {
         uint160 _value;
     }
 
+    /**
+     * @dev Returns the value in the latest checkpoint, or zero if there are no checkpoints.
+     */
     function latest(Trace160 storage self) internal view returns (uint160) {
         uint256 pos = self._checkpoints.length;
         return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
     }
 
+    /**
+     * @dev Pushes a (`key`, `value`) pair into a History so that it is stored as the checkpoint.
+     *
+     * Returns previous value and new value.
+     */
     function push(
         Trace160 storage self,
         uint96 key,
@@ -280,18 +335,27 @@ library Checkpoints {
         return _insert(self._checkpoints, key, value);
     }
 
+    /**
+     * @dev Return the value most recent checkpoint which key is lower or equal than the search key.
+     */
     function lowerLookup(Trace160 storage self, uint96 key) internal view returns (uint160) {
         uint256 length = self._checkpoints.length;
         uint256 pos = _lowerBinaryLookup(self._checkpoints, key, 0, length);
         return pos == length ? 0 : _unsafeAccess(self._checkpoints, pos)._value;
     }
 
+    /**
+     * @dev Return the value oldest checkpoint which key is higher or equal than the search key.
+     */
     function upperLookup(Trace160 storage self, uint96 key) internal view returns (uint160) {
         uint256 length = self._checkpoints.length;
         uint256 pos = _upperBinaryLookup(self._checkpoints, key, 0, length);
         return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
     }
 
+    /**
+     * @dev Return the value oldest checkpoint which key is higher or equal than the search key (similarly to {upperLookupRecent}) doing an exponential lookup first to optimize for recent checkpoints.
+     */
     function upperLookupRecent(Trace160 storage self, uint96 key) internal view returns (uint160) {
         uint256 length = self._checkpoints.length;
         uint256 offset = 1;
@@ -307,6 +371,9 @@ library Checkpoints {
         return pos == 0 ? 0 : _unsafeAccess(self._checkpoints, pos - 1)._value;
     }
 
+    /**
+     * @dev Pushes a (`key`, `value`) pair into a ordered list of checkpoints, either by inserting a new checkpoint, or by updating the last one.
+     */
     function _insert(
         Checkpoint160[] storage self,
         uint96 key,
@@ -315,10 +382,10 @@ library Checkpoints {
         uint256 pos = self.length;
 
         if (pos > 0) {
-            // Use of memory is important here.
+            // Copying to memory is important here.
             Checkpoint160 memory last = _unsafeAccess(self, pos - 1);
 
-            // Checkpoints keys must be increassing.
+            // Checkpoints keys must be increasing.
             require(last._key <= key, "Checkpoint: invalid key");
 
             // Update or push new checkpoint
@@ -334,6 +401,12 @@ library Checkpoints {
         }
     }
 
+    /**
+     * @dev Return the index of the last checkpoint for which `key` >= checkpoint.key, i.e. the most recent checkpoint which key is lower or equal than the search key.
+     * `low` and `high` define a section where to do the search, with an `low` inclusive and `high` exclusive.
+     *
+     * WARNING: `high` should not be greater than the array's length.
+     */
     function _upperBinaryLookup(
         Checkpoint160[] storage self,
         uint96 key,
@@ -351,6 +424,12 @@ library Checkpoints {
         return high;
     }
 
+    /**
+     * @dev Return the index of the first checkpoint for which `key` <= checkpoint.key, i.e. the oldest checkpoint which key is higher or equal than the search key.
+     * `low` and `high` define a section where to do the search, with an `low` inclusive and `high` exclusive.
+     *
+     * WARNING: `high` should not be greater than the array's length.
+     */
     function _lowerBinaryLookup(
         Checkpoint160[] storage self,
         uint96 key,

contracts/utils/math/SafeCast.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/SafeCast.js`.
 // OpenZeppelin Contracts (last updated v4.7.0) (utils/math/SafeCast.sol)
+// This file was procedurally generated from scripts/generate/templates/SafeCast.js.
 
 pragma solidity ^0.8.0;
 

contracts/utils/structs/EnumerableMap.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/EnumerableMap.js`.
 // OpenZeppelin Contracts (last updated v4.7.0) (utils/structs/EnumerableMap.sol)
+// This file was procedurally generated from scripts/generate/templates/EnumerableMap.js.
 
 pragma solidity ^0.8.0;
 

contracts/utils/structs/EnumerableSet.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
-// This file was procedurally generated by `scripts/generate/run.js` from the template file `scripts/generate/templates/EnumerableSet.js`.
 // OpenZeppelin Contracts (last updated v4.7.0) (utils/structs/EnumerableSet.sol)
+// This file was procedurally generated from scripts/generate/templates/EnumerableSet.js.
 
 pragma solidity ^0.8.0;
 

scripts/generate/run.js

@@ -29,14 +29,15 @@ for (const [ file, template ] of Object.entries({
   'utils/Checkpoints.sol': './templates/Checkpoints.js',
   'mocks/CheckpointsMock.sol': './templates/CheckpointsMock.js',
 })) {
-  const script = __filename.replace(path.join(__dirname, '../../'), '');
+  const script = path.relative(path.join(__dirname, '../..'), __filename);
   const input = path.join(path.dirname(script), template);
   const output = `./contracts/${file}`;
   const version = getVersion(output);
   const content = format(
     '// SPDX-License-Identifier: MIT',
-    `// This file was procedurally generated by \`${script}\` from the template file \`${input}\`.`,
-    (version ? version + ` (${file})\n` : ''),
+    ...(version ? [ version + ` (${file})` ] : []),
+    `// This file was procedurally generated from ${input}.`,
+    '',
     require(template),
   );