Add try DoubleEndedQueue functions (#6020)

davidperk · ernestognw · Amxx · web-flow · commit f06bdae6269b · 2025-10-31T14:54:31.000+01:00
Co-authored-by: Ernesto García &lt;ernestognw@gmail.com&gt;
Co-authored-by: Hadrien Croubois &lt;hadrien.croubois@gmail.com&gt;
diff --git a/.changeset/flat-ideas-count.md b/.changeset/flat-ideas-count.md
@@ -0,0 +1,5 @@
+---
+'openzeppelin-solidity': minor
+---
+
+`DoubleEndedQueue`: Add `tryPushBack`, `tryPopBack`, `tryPushFront`, `tryPopFront`, `tryFront`, `tryBack`, and `tryAt` function variants that do not revert.
diff --git a/contracts/utils/structs/DoubleEndedQueue.sol b/contracts/utils/structs/DoubleEndedQueue.sol
@@ -38,11 +38,22 @@ library DoubleEndedQueue {
      * Reverts with {Panic-RESOURCE_ERROR} if the queue is full.
      */
     function pushBack(Bytes32Deque storage deque, bytes32 value) internal {
+        bool success = tryPushBack(deque, value);
+        if (!success) Panic.panic(Panic.RESOURCE_ERROR);
+    }
+
+    /**
+     * @dev Attempts to insert an item at the end of the queue.
+     *
+     * Returns `false` if the queue is full. Never reverts.
+     */
+    function tryPushBack(Bytes32Deque storage deque, bytes32 value) internal returns (bool success) {
         unchecked {
             uint128 backIndex = deque._end;
-            if (backIndex + 1 == deque._begin) Panic.panic(Panic.RESOURCE_ERROR);
+            if (backIndex + 1 == deque._begin) return false;
             deque._data[backIndex] = value;
             deque._end = backIndex + 1;
+            return true;
         }
     }
 
@@ -51,11 +62,23 @@ library DoubleEndedQueue {
      *
      * Reverts with {Panic-EMPTY_ARRAY_POP} if the queue is empty.
      */
-    function popBack(Bytes32Deque storage deque) internal returns (bytes32 value) {
+    function popBack(Bytes32Deque storage deque) internal returns (bytes32) {
+        (bool success, bytes32 value) = tryPopBack(deque);
+        if (!success) Panic.panic(Panic.EMPTY_ARRAY_POP);
+        return value;
+    }
+
+    /**
+     * @dev Attempts to remove the item at the end of the queue and return it.
+     *
+     * Returns `(false, 0x00)` if the queue is empty. Never reverts.
+     */
+    function tryPopBack(Bytes32Deque storage deque) internal returns (bool success, bytes32 value) {
         unchecked {
             uint128 backIndex = deque._end;
-            if (backIndex == deque._begin) Panic.panic(Panic.EMPTY_ARRAY_POP);
+            if (backIndex == deque._begin) return (false, bytes32(0));
             --backIndex;
+            success = true;
             value = deque._data[backIndex];
             delete deque._data[backIndex];
             deque._end = backIndex;
@@ -68,11 +91,22 @@ library DoubleEndedQueue {
      * Reverts with {Panic-RESOURCE_ERROR} if the queue is full.
      */
     function pushFront(Bytes32Deque storage deque, bytes32 value) internal {
+        bool success = tryPushFront(deque, value);
+        if (!success) Panic.panic(Panic.RESOURCE_ERROR);
+    }
+
+    /**
+     * @dev Attempts to insert an item at the beginning of the queue.
+     *
+     * Returns `false` if the queue is full. Never reverts.
+     */
+    function tryPushFront(Bytes32Deque storage deque, bytes32 value) internal returns (bool success) {
         unchecked {
             uint128 frontIndex = deque._begin - 1;
-            if (frontIndex == deque._end) Panic.panic(Panic.RESOURCE_ERROR);
+            if (frontIndex == deque._end) return false;
             deque._data[frontIndex] = value;
             deque._begin = frontIndex;
+            return true;
         }
     }
 
@@ -81,10 +115,23 @@ library DoubleEndedQueue {
      *
      * Reverts with {Panic-EMPTY_ARRAY_POP} if the queue is empty.
      */
-    function popFront(Bytes32Deque storage deque) internal returns (bytes32 value) {
+    function popFront(Bytes32Deque storage deque) internal returns (bytes32) {
+        (bool success, bytes32 value) = tryPopFront(deque);
+        if (!success) Panic.panic(Panic.EMPTY_ARRAY_POP);
+        return value;
+    }
+
+    /**
+     * @dev Attempts to remove the item at the beginning of the queue and
+     * return it.
+     *
+     * Returns `(false, 0x00)` if the queue is empty. Never reverts.
+     */
+    function tryPopFront(Bytes32Deque storage deque) internal returns (bool success, bytes32 value) {
         unchecked {
             uint128 frontIndex = deque._begin;
-            if (frontIndex == deque._end) Panic.panic(Panic.EMPTY_ARRAY_POP);
+            if (frontIndex == deque._end) return (false, bytes32(0));
+            success = true;
             value = deque._data[frontIndex];
             delete deque._data[frontIndex];
             deque._begin = frontIndex + 1;
@@ -96,20 +143,42 @@ library DoubleEndedQueue {
      *
      * Reverts with {Panic-ARRAY_OUT_OF_BOUNDS} if the queue is empty.
      */
-    function front(Bytes32Deque storage deque) internal view returns (bytes32 value) {
-        if (empty(deque)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
-        return deque._data[deque._begin];
+    function front(Bytes32Deque storage deque) internal view returns (bytes32) {
+        (bool success, bytes32 value) = tryFront(deque);
+        if (!success) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
+        return value;
+    }
+
+    /**
+     * @dev Attempts to return the item at the beginning of the queue.
+     *
+     * Returns `(false, 0x00)` if the queue is empty. Never reverts.
+     */
+    function tryFront(Bytes32Deque storage deque) internal view returns (bool success, bytes32 value) {
+        if (empty(deque)) return (false, bytes32(0));
+        return (true, deque._data[deque._begin]);
     }
 
     /**
      * @dev Returns the item at the end of the queue.
      *
      * Reverts with {Panic-ARRAY_OUT_OF_BOUNDS} if the queue is empty.
      */
-    function back(Bytes32Deque storage deque) internal view returns (bytes32 value) {
-        if (empty(deque)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
+    function back(Bytes32Deque storage deque) internal view returns (bytes32) {
+        (bool success, bytes32 value) = tryBack(deque);
+        if (!success) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
+        return value;
+    }
+
+    /**
+     * @dev Attempts to return the item at the end of the queue.
+     *
+     * Returns `(false, 0x00)` if the queue is empty. Never reverts.
+     */
+    function tryBack(Bytes32Deque storage deque) internal view returns (bool success, bytes32 value) {
+        if (empty(deque)) return (false, bytes32(0));
         unchecked {
-            return deque._data[deque._end - 1];
+            return (true, deque._data[deque._end - 1]);
         }
     }
 
@@ -119,11 +188,23 @@ library DoubleEndedQueue {
      *
      * Reverts with {Panic-ARRAY_OUT_OF_BOUNDS} if the index is out of bounds.
      */
-    function at(Bytes32Deque storage deque, uint256 index) internal view returns (bytes32 value) {
-        if (index >= length(deque)) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
+    function at(Bytes32Deque storage deque, uint256 index) internal view returns (bytes32) {
+        (bool success, bytes32 value) = tryAt(deque, index);
+        if (!success) Panic.panic(Panic.ARRAY_OUT_OF_BOUNDS);
+        return value;
+    }
+
+    /**
+     * @dev Attempts to return the item at a position in the queue given by `index`, with the first item at
+     * 0 and the last item at `length(deque) - 1`.
+     *
+     * Returns `(false, 0x00)` if the index is out of bounds. Never reverts.
+     */
+    function tryAt(Bytes32Deque storage deque, uint256 index) internal view returns (bool success, bytes32 value) {
+        if (index >= length(deque)) return (false, bytes32(0));
         // By construction, length is a uint128, so the check above ensures that index can be safely downcast to uint128
         unchecked {
-            return deque._data[deque._begin + uint128(index)];
+            return (true, deque._data[deque._begin + uint128(index)]);
         }
     }
 
diff --git a/test/utils/structs/DoubleEndedQueue.test.js b/test/utils/structs/DoubleEndedQueue.test.js
@@ -26,8 +26,8 @@ describe('DoubleEndedQueue', function () {
 
   describe('when empty', function () {
     it('getters', async function () {
-      expect(await this.mock.$empty(0)).to.be.true;
-      expect(await this.getContent()).to.have.ordered.members([]);
+      await expect(this.mock.$empty(0)).to.eventually.be.true;
+      await expect(this.getContent()).to.eventually.have.ordered.members([]);
     });
 
     it('reverts on accesses', async function () {
@@ -36,6 +36,24 @@ describe('DoubleEndedQueue', function () {
       await expect(this.mock.$back(0)).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
       await expect(this.mock.$front(0)).to.be.revertedWithPanic(PANIC_CODES.ARRAY_ACCESS_OUT_OF_BOUNDS);
     });
+
+    it('try getters return false/zero on empty', async function () {
+      await expect(this.mock.$tryFront(0)).to.eventually.deep.equal([false, ethers.ZeroHash]);
+      await expect(this.mock.$tryBack(0)).to.eventually.deep.equal([false, ethers.ZeroHash]);
+      await expect(this.mock.$tryAt(0, 0)).to.eventually.deep.equal([false, ethers.ZeroHash]);
+    });
+
+    it('try pops return false/zero on empty', async function () {
+      await expect(this.mock.$tryPopFront(0)).to.emit(this.mock, 'return$tryPopFront').withArgs(false, ethers.ZeroHash);
+      await expect(this.mock.$tryPopBack(0)).to.emit(this.mock, 'return$tryPopBack').withArgs(false, ethers.ZeroHash);
+    });
+
+    it('try pushes succeed on empty', async function () {
+      await expect(this.mock.$tryPushFront(0, bytesA)).to.emit(this.mock, 'return$tryPushFront').withArgs(true);
+      await expect(this.mock.$tryPushBack(0, bytesB)).to.emit(this.mock, 'return$tryPushBack').withArgs(true);
+
+      await expect(this.getContent()).to.eventually.have.ordered.members([bytesA, bytesB]);
+    });
   });
 
   describe('when not empty', function () {
@@ -47,11 +65,11 @@ describe('DoubleEndedQueue', function () {
     });
 
     it('getters', async function () {
-      expect(await this.mock.$empty(0)).to.be.false;
-      expect(await this.mock.$length(0)).to.equal(this.content.length);
-      expect(await this.mock.$front(0)).to.equal(this.content[0]);
-      expect(await this.mock.$back(0)).to.equal(this.content[this.content.length - 1]);
-      expect(await this.getContent()).to.have.ordered.members(this.content);
+      await expect(this.mock.$empty(0)).to.eventually.be.false;
+      await expect(this.mock.$length(0)).to.eventually.equal(this.content.length);
+      await expect(this.mock.$front(0)).to.eventually.equal(this.content[0]);
+      await expect(this.mock.$back(0)).to.eventually.equal(this.content[this.content.length - 1]);
+      await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
     });
 
     it('out of bounds access', async function () {
@@ -60,19 +78,29 @@ describe('DoubleEndedQueue', function () {
       );
     });
 
+    it('try getters return true/value when not empty', async function () {
+      await expect(this.mock.$tryFront(0)).to.eventually.deep.equal([true, this.content[0]]);
+      await expect(this.mock.$tryBack(0)).to.eventually.deep.equal([true, this.content[this.content.length - 1]]);
+      await expect(this.mock.$tryAt(0, 1)).to.eventually.deep.equal([true, this.content[1]]);
+    });
+
+    it('tryAt returns false/zero on out of bounds', async function () {
+      await expect(this.mock.$tryAt(0, this.content.length)).to.eventually.deep.equal([false, ethers.ZeroHash]);
+    });
+
     describe('push', function () {
       it('front', async function () {
         await this.mock.$pushFront(0, bytesD);
         this.content.unshift(bytesD); // add element at the beginning
 
-        expect(await this.getContent()).to.have.ordered.members(this.content);
+        await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
       });
 
       it('back', async function () {
         await this.mock.$pushBack(0, bytesD);
         this.content.push(bytesD); // add element at the end
 
-        expect(await this.getContent()).to.have.ordered.members(this.content);
+        await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
       });
     });
 
@@ -81,22 +109,36 @@ describe('DoubleEndedQueue', function () {
         const value = this.content.shift(); // remove first element
         await expect(this.mock.$popFront(0)).to.emit(this.mock, 'return$popFront').withArgs(value);
 
-        expect(await this.getContent()).to.have.ordered.members(this.content);
+        await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
       });
 
       it('back', async function () {
         const value = this.content.pop(); // remove last element
         await expect(this.mock.$popBack(0)).to.emit(this.mock, 'return$popBack').withArgs(value);
 
-        expect(await this.getContent()).to.have.ordered.members(this.content);
+        await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
+      });
+
+      it('try front', async function () {
+        const value = this.content.shift();
+        await expect(this.mock.$tryPopFront(0)).to.emit(this.mock, 'return$tryPopFront').withArgs(true, value);
+
+        await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
+      });
+
+      it('try back', async function () {
+        const value = this.content.pop();
+        await expect(this.mock.$tryPopBack(0)).to.emit(this.mock, 'return$tryPopBack').withArgs(true, value);
+
+        await expect(this.getContent()).to.eventually.have.ordered.members(this.content);
       });
     });
 
     it('clear', async function () {
       await this.mock.$clear(0);
 
-      expect(await this.mock.$empty(0)).to.be.true;
-      expect(await this.getContent()).to.have.ordered.members([]);
+      await expect(this.mock.$empty(0)).to.eventually.be.true;
+      await expect(this.getContent()).to.eventually.have.ordered.members([]);
     });
   });
 });

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'openzeppelin-solidity': minor
 +---
++
 +`DoubleEndedQueue`: Add `tryPushBack`, `tryPopBack`, `tryPushFront`, `tryPopFront`, `tryFront`, `tryBack`, and `tryAt` function variants that do not revert.