rename top -> peek

contracts/utils/structs/Heap.sol

@@ -27,9 +27,10 @@ library Heap {
      * smallest value is the one at the root. It can be retrieved in O(1) at `heap.data[heap.data[0].index].value`
      *
      * This structure is designed for the following complexities:
-     * - insert: 0(log(n))
-     * - pop (remove smallest value in set): O(log(n))
-     * - top (get smallest value in set): O(1)
+     * - peek (get the smallest value in set): O(1)
+     * - insert (insert a value in the set): 0(log(n))
+     * - pop (remove the smallest value in set): O(log(n))
+     * - replace (replace the smallest value in set with a new value): O(log(n))
      */
     struct Uint256Heap {
         Uint256HeapNode[] data;
@@ -44,7 +45,7 @@ library Heap {
     /**
      * @dev Lookup the root element of the heap.
      */
-    function top(Uint256Heap storage self) internal view returns (uint256) {
+    function peek(Uint256Heap storage self) internal view returns (uint256) {
         return _unsafeNodeAccess(self, self.data[0].index).value;
     }
 
@@ -140,6 +141,7 @@ library Heap {
 
     /**
      * @dev Return the root element for the heap, and replace it with a new value, using the default comparator.
+     * This is equivalent to using {pop} and {insert}, but requires only one rebalancing operation.
      *
      * Note: All inserting and removal from a heap should always be done using the same comparator. Mixing comparator
      * during the lifecycle of a heap will result in undefined behavior.
@@ -150,6 +152,7 @@ library Heap {
 
     /**
      * @dev Return the root element for the heap, and replace it with a new value, using the provided comparator.
+     * This is equivalent to using {pop} and {insert}, but requires only one rebalancing operation.
      *
      * Note: All inserting and removal from a heap should always be done using the same comparator. Mixing comparator
      * during the lifecycle of a heap will result in undefined behavior.
@@ -305,9 +308,10 @@ library Heap {
      * smallest value is the one at the root. It can be retrieved in O(1) at `heap.data[heap.data[0].index].value`
      *
      * This structure is designed for the following complexities:
-     * - insert: 0(log(n))
-     * - pop (remove smallest value in set): O(log(n))
-     * - top (get smallest value in set): O(1)
+     * - peek (get the smallest value in set): O(1)
+     * - insert (insert a value in the set): 0(log(n))
+     * - pop (remove the smallest value in set): O(log(n))
+     * - replace (replace the smallest value in set with a new value): O(log(n))
      */
     struct Uint208Heap {
         Uint208HeapNode[] data;
@@ -322,7 +326,7 @@ library Heap {
     /**
      * @dev Lookup the root element of the heap.
      */
-    function top(Uint208Heap storage self) internal view returns (uint208) {
+    function peek(Uint208Heap storage self) internal view returns (uint208) {
         return _unsafeNodeAccess(self, self.data[0].index).value;
     }
 
@@ -418,6 +422,7 @@ library Heap {
 
     /**
      * @dev Return the root element for the heap, and replace it with a new value, using the default comparator.
+     * This is equivalent to using {pop} and {insert}, but requires only one rebalancing operation.
      *
      * Note: All inserting and removal from a heap should always be done using the same comparator. Mixing comparator
      * during the lifecycle of a heap will result in undefined behavior.
@@ -428,6 +433,7 @@ library Heap {
 
     /**
      * @dev Return the root element for the heap, and replace it with a new value, using the provided comparator.
+     * This is equivalent to using {pop} and {insert}, but requires only one rebalancing operation.
      *
      * Note: All inserting and removal from a heap should always be done using the same comparator. Mixing comparator
      * during the lifecycle of a heap will result in undefined behavior.

scripts/generate/templates/Heap.js

@@ -29,9 +29,10 @@ const generate = ({ struct, node, valueType, indexType, blockSize }) => `\
  * smallest value is the one at the root. It can be retrieved in O(1) at \`heap.data[heap.data[0].index].value\`
  *
  * This structure is designed for the following complexities:
- * - insert: 0(log(n))
- * - pop (remove smallest value in set): O(log(n))
- * - top (get smallest value in set): O(1)
+ * - peek (get the smallest value in set): O(1)
+ * - insert (insert a value in the set): 0(log(n))
+ * - pop (remove the smallest value in set): O(log(n))
+ * - replace (replace the smallest value in set with a new value): O(log(n))
  */
 struct ${struct} {
     ${node}[] data;
@@ -46,7 +47,7 @@ struct ${node} {
 /**
  * @dev Lookup the root element of the heap.
  */
-function top(${struct} storage self) internal view returns (${valueType}) {
+function peek(${struct} storage self) internal view returns (${valueType}) {
     return _unsafeNodeAccess(self, self.data[0].index).value;
 }
 
@@ -142,6 +143,7 @@ function insert(
 
 /**
  * @dev Return the root element for the heap, and replace it with a new value, using the default comparator.
+ * This is equivalent to using {pop} and {insert}, but requires only one rebalancing operation.
  *
  * Note: All inserting and removal from a heap should always be done using the same comparator. Mixing comparator
  * during the lifecycle of a heap will result in undefined behavior.
@@ -152,6 +154,7 @@ function replace(${struct} storage self, ${valueType} newValue) internal returns
 
 /**
  * @dev Return the root element for the heap, and replace it with a new value, using the provided comparator.
+ * This is equivalent to using {pop} and {insert}, but requires only one rebalancing operation.
  *
  * Note: All inserting and removal from a heap should always be done using the same comparator. Mixing comparator
  * during the lifecycle of a heap will result in undefined behavior.

test/utils/structs/Heap.t.sol

@@ -35,12 +35,12 @@ contract Uint256HeapTest is Test {
             _validateHeap(Comparators.lt);
 
             min = Math.min(min, input[i]);
-            assertEq(heap.top(), min);
+            assertEq(heap.peek(), min);
         }
 
         uint256 max = 0;
         for (uint256 i = 0; i < input.length; ++i) {
-            uint256 top = heap.top();
+            uint256 top = heap.peek();
             uint256 pop = heap.pop();
             assertEq(heap.length(), input.length - i - 1);
             _validateHeap(Comparators.lt);
@@ -62,12 +62,12 @@ contract Uint256HeapTest is Test {
             _validateHeap(Comparators.gt);
 
             max = Math.max(max, input[i]);
-            assertEq(heap.top(), max);
+            assertEq(heap.peek(), max);
         }
 
         uint256 min = type(uint256).max;
         for (uint256 i = 0; i < input.length; ++i) {
-            uint256 top = heap.top();
+            uint256 top = heap.peek();
             uint256 pop = heap.pop(Comparators.gt);
             assertEq(heap.length(), input.length - i - 1);
             _validateHeap(Comparators.gt);
@@ -106,12 +106,12 @@ contract Uint208HeapTest is Test {
             _validateHeap(Comparators.lt);
 
             min = Math.min(min, input[i]);
-            assertEq(heap.top(), min);
+            assertEq(heap.peek(), min);
         }
 
         uint256 max = 0;
         for (uint256 i = 0; i < input.length; ++i) {
-            uint208 top = heap.top();
+            uint208 top = heap.peek();
             uint208 pop = heap.pop();
             assertEq(heap.length(), input.length - i - 1);
             _validateHeap(Comparators.lt);
@@ -133,12 +133,12 @@ contract Uint208HeapTest is Test {
             _validateHeap(Comparators.gt);
 
             max = Math.max(max, input[i]);
-            assertEq(heap.top(), max);
+            assertEq(heap.peek(), max);
         }
 
         uint256 min = type(uint256).max;
         for (uint256 i = 0; i < input.length; ++i) {
-            uint208 top = heap.top();
+            uint208 top = heap.peek();
             uint208 pop = heap.pop(Comparators.gt);
             assertEq(heap.length(), input.length - i - 1);
             _validateHeap(Comparators.gt);

test/utils/structs/Heap.test.js

@@ -27,12 +27,12 @@ describe('Heap', function () {
           replace: (...args) => this.mock[`$replace(uint256,${valueType})`](0, ...args),
           length: (...args) => this.mock[`$length_Heap_${struct}`](0, ...args),
           pop: (...args) => this.mock[`$pop_Heap_${struct}`](0, ...args),
-          top: (...args) => this.mock[`$top_Heap_${struct}`](0, ...args),
+          peek: (...args) => this.mock[`$peek_Heap_${struct}`](0, ...args),
         };
       });
 
       it('starts empty', async function () {
-        await expect(this.helper.top()).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
+        await expect(this.helper.peek()).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
         expect(await this.helper.length()).to.equal(0n);
       });
 
@@ -44,12 +44,12 @@ describe('Heap', function () {
         await this.helper.insert(42n);
 
         expect(await this.helper.length()).to.equal(1n);
-        expect(await this.helper.top()).to.equal(42n);
+        expect(await this.helper.peek()).to.equal(42n);
 
         await this.helper.clear();
 
         expect(await this.helper.length()).to.equal(0n);
-        await expect(this.helper.top()).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
+        await expect(this.helper.peek()).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
       });
 
       it('support duplicated items', async function () {
@@ -119,9 +119,9 @@ describe('Heap', function () {
           }
           expect(await this.helper.length()).to.equal(heap.length);
           if (heap.length == 0) {
-            await expect(this.helper.top()).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
+            await expect(this.helper.peek()).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
           } else {
-            expect(await this.helper.top()).to.equal(heap[0]);
+            expect(await this.helper.peek()).to.equal(heap[0]);
           }
         }
       });