add memory variants

contracts/mocks/ArraysMock.sol

@@ -13,12 +13,24 @@ contract Uint256ArraysMock {
         _array = array;
     }
 
-    function findUpperBound(uint256 element) external view returns (uint256) {
-        return _array.findUpperBound(element);
+    function findUpperBound(uint256 value) external view returns (uint256) {
+        return _array.findUpperBound(value);
     }
 
-    function findLowerBound(uint256 element) external view returns (uint256) {
-        return _array.findLowerBound(element);
+    function lowerBound(uint256 value) external view returns (uint256) {
+        return _array.lowerBound(value);
+    }
+
+    function upperBound(uint256 value) external view returns (uint256) {
+        return _array.upperBound(value);
+    }
+
+    function lowerBoundMemory(uint256[] memory array, uint256 value) external pure returns (uint256) {
+        return array.lowerBoundMemory(value);
+    }
+
+    function upperBoundMemory(uint256[] memory array, uint256 value) external pure returns (uint256) {
+        return array.upperBoundMemory(value);
     }
 
     function unsafeAccess(uint256 pos) external view returns (uint256) {

contracts/utils/Arrays.sol

@@ -20,6 +20,9 @@ library Arrays {
      *
      * `array` is expected to be sorted in ascending order, and to contain no
      * repeated elements.
+     *
+     * Deprecated in favor of `lowerBound` and `findUpperBound`. Note that this actually implements a lower bound
+     * search, and should be replaced with `lowerBound`
      */
     function findUpperBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
         uint256 low = 0;
@@ -29,6 +32,44 @@ library Arrays {
             return 0;
         }
 
+        while (low < high) {
+            uint256 mid = Math.average(low, high);
+
+            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
+            // because Math.average rounds towards zero (it does integer division with truncation).
+            if (unsafeAccess(array, mid).value > element) {
+                high = mid;
+            } else {
+                low = mid + 1;
+            }
+        }
+
+        // At this point `low` is the exclusive upper bound. We will return the inclusive upper bound.
+        if (low > 0 && unsafeAccess(array, low - 1).value == element) {
+            return low - 1;
+        } else {
+            return low;
+        }
+    }
+
+    /**
+     * @dev Searches a sorted `array` and returns the first index that contains
+     * a value greater or equal to `element`. If no such index exists (i.e. all
+     * values in the array are strictly less than `element`), the array length is
+     * returned. Time complexity O(log n).
+     *
+     * `array` is expected to be sorted in ascending order,
+     *
+     * See https://en.cppreference.com/w/cpp/algorithm/ranges/lower_bound
+     */
+    function lowerBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
+        uint256 low = 0;
+        uint256 high = array.length;
+
+        if (high == 0) {
+            return 0;
+        }
+
         while (low < high) {
             uint256 mid = Math.average(low, high);
 
@@ -48,24 +89,111 @@ library Arrays {
     }
 
     /**
-     * @dev Searches a sorted `array` and returns the last index that contains
-     * a value smaller or equal to `element`. If no such index exists (i.e. all
-     * values in the array are strictly greater than `element`), the array length is
+     * @dev Searches a sorted `array` and returns the first index that contains
+     * a value strictly greater to `element`. If no such index exists (i.e. all
+     * values in the array are strictly less than `element`), the array length is
      * returned. Time complexity O(log n).
      *
-     * `array` is expected to be sorted in ascending order, and to contain no
-     * repeated elements.
+     * `array` is expected to be sorted in ascending order,
+     *
+     * See https://en.cppreference.com/w/cpp/algorithm/upper_bound
      */
-    function findLowerBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
-        // following math cannot overflow
-        unchecked {
-            uint256 length = array.length;
-            if (element == type(uint256).max) {
-                return length == 0 ? 0 : length - 1;
+    function upperBound(uint256[] storage array, uint256 element) internal view returns (uint256) {
+        uint256 low = 0;
+        uint256 high = array.length;
+
+        if (high == 0) {
+            return 0;
+        }
+
+        while (low < high) {
+            uint256 mid = Math.average(low, high);
+
+            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
+            // because Math.average rounds towards zero (it does integer division with truncation).
+            if (unsafeAccess(array, mid).value > element) {
+                high = mid;
+            } else {
+                // this cannot overflow because mid < high
+                unchecked {
+                    low = mid + 1;
+                }
             }
-            uint256 upperBoundForNext = findUpperBound(array, element + 1);
-            return upperBoundForNext == 0 ? length : upperBoundForNext - 1;
         }
+
+        return low;
+    }
+
+    /**
+     * @dev Searches a sorted `array` and returns the first index that contains
+     * a value greater or equal to `element`. If no such index exists (i.e. all
+     * values in the array are strictly less than `element`), the array length is
+     * returned. Time complexity O(log n).
+     *
+     * `array` is expected to be sorted in ascending order,
+     *
+     * See https://en.cppreference.com/w/cpp/algorithm/ranges/lower_bound
+     */
+    function lowerBoundMemory(uint256[] memory array, uint256 element) internal pure returns (uint256) {
+        uint256 low = 0;
+        uint256 high = array.length;
+
+        if (high == 0) {
+            return 0;
+        }
+
+        while (low < high) {
+            uint256 mid = Math.average(low, high);
+
+            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
+            // because Math.average rounds towards zero (it does integer division with truncation).
+            if (unsafeMemoryAccess(array, mid) < element) {
+                // this cannot overflow because mid < high
+                unchecked {
+                    low = mid + 1;
+                }
+            } else {
+                high = mid;
+            }
+        }
+
+        return low;
+    }
+
+    /**
+     * @dev Searches a sorted `array` and returns the first index that contains
+     * a value strictly greater to `element`. If no such index exists (i.e. all
+     * values in the array are strictly less than `element`), the array length is
+     * returned. Time complexity O(log n).
+     *
+     * `array` is expected to be sorted in ascending order,
+     *
+     * See https://en.cppreference.com/w/cpp/algorithm/upper_bound
+     */
+    function upperBoundMemory(uint256[] memory array, uint256 element) internal pure returns (uint256) {
+        uint256 low = 0;
+        uint256 high = array.length;
+
+        if (high == 0) {
+            return 0;
+        }
+
+        while (low < high) {
+            uint256 mid = Math.average(low, high);
+
+            // Note that mid will always be strictly less than high (i.e. it will be a valid array index)
+            // because Math.average rounds towards zero (it does integer division with truncation).
+            if (unsafeMemoryAccess(array, mid) > element) {
+                high = mid;
+            } else {
+                // this cannot overflow because mid < high
+                unchecked {
+                    low = mid + 1;
+                }
+            }
+        }
+
+        return low;
     }
 
     /**

test/utils/Arrays.test.js

@@ -2,61 +2,65 @@ const { ethers } = require('hardhat');
 const { expect } = require('chai');
 const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');
 
-const findUpperBound = (array, value) => {
-  const i = array.findIndex(x => x >= value);
+// See https://en.cppreference.com/w/cpp/algorithm/ranges/lower_bound
+const lowerBound = (array, value) => {
+  const i = array.findIndex(element => value <= element);
   return i == -1 ? array.length : i;
 };
 
-const findLowerBound = (array, value) => {
-  const i = array.findLastIndex(x => x <= value);
+// See https://en.cppreference.com/w/cpp/algorithm/upper_bound
+const upperBound = (array, value) => {
+  const i = array.findIndex(element => value < element);
   return i == -1 ? array.length : i;
 };
 
+const hasDuplicates = array => array.some((v, i) => array.indexOf(v) != i);
+
 describe('Arrays', function () {
-  describe('findUpperBound', function () {
+  describe('search', function () {
     for (const [title, { array, tests }] of Object.entries({
       'Even number of elements': {
         array: [11n, 12n, 13n, 14n, 15n, 16n, 17n, 18n, 19n, 20n],
         tests: {
-          'returns correct index for the basic case': 16n,
-          'returns 0 for the first element': 11n,
-          'returns index of the last element': 20n,
-          'returns first index after last element if searched value is over the upper boundary': 32n,
-          'returns 0 for the element under the lower boundary': 2n,
+          'basic case': 16n,
+          'first element': 11n,
+          'last element': 20n,
+          'searched value is over the upper boundary': 32n,
+          'searched value is under the lower boundary': 2n,
         },
       },
       'Odd number of elements': {
         array: [11n, 12n, 13n, 14n, 15n, 16n, 17n, 18n, 19n, 20n, 21n],
         tests: {
-          'returns correct index for the basic case': 16n,
-          'returns 0 for the first element': 11n,
-          'returns index of the last element': 20n,
-          'returns first index after last element if searched value is over the upper boundary': 32n,
-          'returns 0 for the element under the lower boundary': 2n,
+          'basic case': 16n,
+          'first element': 11n,
+          'last element': 21n,
+          'searched value is over the upper boundary': 32n,
+          'searched value is under the lower boundary': 2n,
         },
       },
       'Array with gap': {
         array: [11n, 12n, 13n, 14n, 15n, 20n, 21n, 22n, 23n, 24n],
         tests: {
-          'returns index of first element in next filled range': 17n,
+          'search value in gap': 17n,
         },
       },
       'Array with duplicated elements': {
         array: [0n, 10n, 10n, 10n, 10n, 10n, 10n, 10n, 20n],
         tests: {
-          'returns index of first occurence': 10n,
+          'search value is duplicated': 10n,
         },
       },
       'Array with duplicated first element': {
         array: [10n, 10n, 10n, 10n, 10n, 10n, 10n, 20n],
         tests: {
-          'returns index of first occurence': 10n,
+          'search value is duplicated first element': 10n,
         },
       },
       'Array with duplicated last element': {
         array: [0n, 10n, 10n, 10n, 10n, 10n, 10n, 10n],
         tests: {
-          'returns index of first occurence': 10n,
+          'search value is duplicated last element': 10n,
         },
       },
       'Empty array': {
@@ -76,79 +80,22 @@ describe('Arrays', function () {
         });
 
         for (const [name, input] of Object.entries(tests)) {
-          it(name, async function () {
-            expect(await this.mock.findUpperBound(input)).to.be.equal(findUpperBound(array, input));
-          });
-        }
-      });
-    }
-  });
+          describe(name, function () {
+            it('[deprecated] findUpperBound', async function () {
+              // findUpperBound does not support duplicated
+              if (hasDuplicates(array)) this.skip();
+              expect(await this.mock.findUpperBound(input)).to.be.equal(lowerBound(array, input));
+            });
 
-  describe('findLowerBound', function () {
-    for (const [title, { array, tests }] of Object.entries({
-      'Even number of elements': {
-        array: [11n, 12n, 13n, 14n, 15n, 16n, 17n, 18n, 19n, 20n],
-        tests: {
-          'returns correct index for the basic case': 16n,
-          'returns 0 for the first element': 11n,
-          'returns index of the last element': 20n,
-          'returns index of last element if searched value is over the upper boundary': 32n,
-          'returns length for the element under the lower boundary': 2n,
-        },
-      },
-      'Odd number of elements': {
-        array: [11n, 12n, 13n, 14n, 15n, 16n, 17n, 18n, 19n, 20n, 21n],
-        tests: {
-          'returns correct index for the basic case': 16n,
-          'returns 0 for the first element': 11n,
-          'returns index of the last element': 20n,
-          'returns index of last element if searched value is over the upper boundary': 32n,
-          'returns length for the element under the lower boundary': 2n,
-        },
-      },
-      'Array with gap': {
-        array: [11n, 12n, 13n, 14n, 15n, 20n, 21n, 22n, 23n, 24n],
-        tests: {
-          'returns index of first element in next filled range': 17n,
-        },
-      },
-      'Array with duplicated elements': {
-        array: [0n, 10n, 10n, 10n, 10n, 10n, 10n, 10n, 20n],
-        tests: {
-          'returns index of last occurence': 10n,
-        },
-      },
-      'Array with duplicated first element': {
-        array: [10n, 10n, 10n, 10n, 10n, 10n, 10n, 20n],
-        tests: {
-          'returns index of last occurence': 10n,
-        },
-      },
-      'Array with duplicated last element': {
-        array: [0n, 10n, 10n, 10n, 10n, 10n, 10n, 10n],
-        tests: {
-          'returns index of last occurence': 10n,
-        },
-      },
-      'Empty array': {
-        array: [],
-        tests: {
-          'always returns 0 for empty array': 10n,
-        },
-      },
-    })) {
-      describe(title, function () {
-        const fixture = async () => {
-          return { mock: await ethers.deployContract('Uint256ArraysMock', [array]) };
-        };
-
-        beforeEach(async function () {
-          Object.assign(this, await loadFixture(fixture));
-        });
+            it('lowerBound', async function () {
+              expect(await this.mock.lowerBound(input)).to.be.equal(lowerBound(array, input));
+              expect(await this.mock.lowerBoundMemory(array, input)).to.be.equal(lowerBound(array, input));
+            });
 
-        for (const [name, input] of Object.entries(tests)) {
-          it(name, async function () {
-            expect(await this.mock.findLowerBound(input)).to.be.equal(findLowerBound(array, input));
+            it('upperBound', async function () {
+              expect(await this.mock.upperBound(input)).to.be.equal(upperBound(array, input));
+              expect(await this.mock.upperBoundMemory(array, input)).to.be.equal(upperBound(array, input));
+            });
           });
         }
       });