Add paginated version of EnumerableSet.values() and EnumerableMap.keys() (#5713)

Co-authored-by: ernestognw <ernestognw@gmail.com>

contracts/utils/structs/EnumerableMap.sol

@@ -164,7 +164,7 @@ library EnumerableMap {
     }
 
     /**
-     * @dev Return the an array containing all the keys
+     * @dev Returns an array containing all the keys
      *
      * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
      * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
@@ -175,6 +175,22 @@ library EnumerableMap {
         return map._keys.values();
     }
 
+    /**
+     * @dev Returns an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(
+        Bytes32ToBytes32Map storage map,
+        uint256 start,
+        uint256 end
+    ) internal view returns (bytes32[] memory) {
+        return map._keys.values(start, end);
+    }
+
     // UintToUintMap
 
     struct UintToUintMap {
@@ -278,6 +294,25 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(UintToUintMap storage map, uint256 start, uint256 end) internal view returns (uint256[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        uint256[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // UintToAddressMap
 
     struct UintToAddressMap {
@@ -381,6 +416,25 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(UintToAddressMap storage map, uint256 start, uint256 end) internal view returns (uint256[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        uint256[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // UintToBytes32Map
 
     struct UintToBytes32Map {
@@ -484,6 +538,25 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(UintToBytes32Map storage map, uint256 start, uint256 end) internal view returns (uint256[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        uint256[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // AddressToUintMap
 
     struct AddressToUintMap {
@@ -587,6 +660,25 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(AddressToUintMap storage map, uint256 start, uint256 end) internal view returns (address[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        address[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // AddressToAddressMap
 
     struct AddressToAddressMap {
@@ -690,6 +782,29 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(
+        AddressToAddressMap storage map,
+        uint256 start,
+        uint256 end
+    ) internal view returns (address[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        address[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // AddressToBytes32Map
 
     struct AddressToBytes32Map {
@@ -793,6 +908,29 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(
+        AddressToBytes32Map storage map,
+        uint256 start,
+        uint256 end
+    ) internal view returns (address[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        address[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // Bytes32ToUintMap
 
     struct Bytes32ToUintMap {
@@ -896,6 +1034,25 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(Bytes32ToUintMap storage map, uint256 start, uint256 end) internal view returns (bytes32[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        bytes32[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // Bytes32ToAddressMap
 
     struct Bytes32ToAddressMap {
@@ -999,6 +1156,29 @@ library EnumerableMap {
         return result;
     }
 
+    /**
+     * @dev Return the an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(
+        Bytes32ToAddressMap storage map,
+        uint256 start,
+        uint256 end
+    ) internal view returns (bytes32[] memory) {
+        bytes32[] memory store = keys(map._inner, start, end);
+        bytes32[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     /**
      * @dev Query for a nonexistent map key.
      */
@@ -1106,7 +1286,7 @@ library EnumerableMap {
     }
 
     /**
-     * @dev Return the an array containing all the keys
+     * @dev Returns an array containing all the keys
      *
      * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
      * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
@@ -1116,4 +1296,16 @@ library EnumerableMap {
     function keys(BytesToBytesMap storage map) internal view returns (bytes[] memory) {
         return map._keys.values();
     }
+
+    /**
+     * @dev Returns an array containing a slice of the keys
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the map grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function keys(BytesToBytesMap storage map, uint256 start, uint256 end) internal view returns (bytes[] memory) {
+        return map._keys.values(start, end);
+    }
 }

contracts/utils/structs/EnumerableSet.sol

@@ -5,6 +5,7 @@
 pragma solidity ^0.8.20;
 
 import {Arrays} from "../Arrays.sol";
+import {Math} from "../math/Math.sol";
 
 /**
  * @dev Library for managing
@@ -176,6 +177,28 @@ library EnumerableSet {
         return set._values;
     }
 
+    /**
+     * @dev Return a slice of the set in an array
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function _values(Set storage set, uint256 start, uint256 end) private view returns (bytes32[] memory) {
+        unchecked {
+            end = Math.min(end, _length(set));
+            start = Math.min(start, end);
+
+            uint256 len = end - start;
+            bytes32[] memory result = new bytes32[](len);
+            for (uint256 i = 0; i < len; ++i) {
+                result[i] = Arrays.unsafeAccess(set._values, start + i).value;
+            }
+            return result;
+        }
+    }
+
     // Bytes32Set
 
     struct Bytes32Set {
@@ -259,6 +282,25 @@ library EnumerableSet {
         return result;
     }
 
+    /**
+     * @dev Return a slice of the set in an array
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function values(Bytes32Set storage set, uint256 start, uint256 end) internal view returns (bytes32[] memory) {
+        bytes32[] memory store = _values(set._inner, start, end);
+        bytes32[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // AddressSet
 
     struct AddressSet {
@@ -342,6 +384,25 @@ library EnumerableSet {
         return result;
     }
 
+    /**
+     * @dev Return a slice of the set in an array
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function values(AddressSet storage set, uint256 start, uint256 end) internal view returns (address[] memory) {
+        bytes32[] memory store = _values(set._inner, start, end);
+        address[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     // UintSet
 
     struct UintSet {
@@ -425,6 +486,25 @@ library EnumerableSet {
         return result;
     }
 
+    /**
+     * @dev Return a slice of the set in an array
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function values(UintSet storage set, uint256 start, uint256 end) internal view returns (uint256[] memory) {
+        bytes32[] memory store = _values(set._inner, start, end);
+        uint256[] memory result;
+
+        assembly ("memory-safe") {
+            result := store
+        }
+
+        return result;
+    }
+
     struct StringSet {
         // Storage of set values
         string[] _values;
@@ -545,6 +625,28 @@ library EnumerableSet {
         return self._values;
     }
 
+    /**
+     * @dev Return a slice of the set in an array
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function values(StringSet storage set, uint256 start, uint256 end) internal view returns (string[] memory) {
+        unchecked {
+            end = Math.min(end, length(set));
+            start = Math.min(start, end);
+
+            uint256 len = end - start;
+            string[] memory result = new string[](len);
+            for (uint256 i = 0; i < len; ++i) {
+                result[i] = Arrays.unsafeAccess(set._values, start + i).value;
+            }
+            return result;
+        }
+    }
+
     struct BytesSet {
         // Storage of set values
         bytes[] _values;
@@ -664,4 +766,26 @@ library EnumerableSet {
     function values(BytesSet storage self) internal view returns (bytes[] memory) {
         return self._values;
     }
+
+    /**
+     * @dev Return a slice of the set in an array
+     *
+     * WARNING: This operation will copy the entire storage to memory, which can be quite expensive. This is designed
+     * to mostly be used by view accessors that are queried without any gas fees. Developers should keep in mind that
+     * this function has an unbounded cost, and using it as part of a state-changing function may render the function
+     * uncallable if the set grows to a point where copying to memory consumes too much gas to fit in a block.
+     */
+    function values(BytesSet storage set, uint256 start, uint256 end) internal view returns (bytes[] memory) {
+        unchecked {
+            end = Math.min(end, length(set));
+            start = Math.min(start, end);
+
+            uint256 len = end - start;
+            bytes[] memory result = new bytes[](len);
+            for (uint256 i = 0; i < len; ++i) {
+                result[i] = Arrays.unsafeAccess(set._values, start + i).value;
+            }
+            return result;
+        }
+    }
 }