---
title: "Adding clear() to Container Adaptors"
document: P4343R0
date: 2026-08-11
audience: Library Evolution Working Group (LEWG)
reply-to:
  - "Shubham Avasthi"
  - "Shubham Avasthi <shubhamavasthi1@gmail.com>"
---

:::wording-add

Currently, there is no standardized, zero-overhead way to clear the elements of container adaptors. When developers need to reuse a <ins>std::priority_queue or std::queue</ins> in a performance-critical loop, they are forced to use one of two suboptimal workarounds:

:::

**Workaround 1: Looping and Popping** `while` `(!pq.empty()) {` `pq.pop();` `}`

:::wording-add

For a <ins>std::priority_queue</ins>, this is highly inefficient. It forces the container to rebuild the heap structure on every single pop, resulting in a time complexity of O(N log N).

:::

**Workaround 2: Reassignment** `pq =` `std``::priority_queue<T>();`

While this operation clears the elements quickly, it completely destroys the underlying container and its allocated memory. Subsequent insertions will trigger expensive dynamic memory reallocations, violating the core C++ principle of zero-cost abstractions.

### 4. Design Decisions

:::wording-add

We propose adding a <ins>clear() member function to std::priority_queue, std::queue</ins>, and <ins>std::stack</ins>.

:::

:::wording-add

● Conditional Compilation: To prevent breaking legacy code that uses custom SequenceContainers lacking a <ins>.clear()</ins> method, the proposed function is constrained using a <ins>requires clause. It will only participate in overload resolution if c.clear()</ins> is a valid expression.

:::

:::wording-add

● <ins>constexpr</ins> Support: In alignment with C++20's push to make standard containers usable at compile-time, the <ins>clear() method is marked constexpr</ins>.

:::

:::wording-add

● Exception Specification: The method unconditionally delegates to the underlying container's <ins>clear() method and perfectly propagates its noexcept</ins> specification.

:::

### 5. Proposed Wording

The proposed changes are relative to the current working draft of the C++ Standard.

:::wording-add

Modify <ins>[queue.defn]</ins> (Queue definition):

:::

```cpp
namespace std {
  template<class T, class Container = deque<T>>
  class queue {
  public:
    // ... existing members ...
    constexpr void pop() { c.pop_front(); }
    
    constexpr void clear() noexcept(noexcept(c.clear())) 
      requires requires { c.clear(); } 
    { 
      c.clear(); 
    }
  };
} 
```

:::wording-add

Modify <ins>[priority.queue]</ins> (Priority queue definition):

:::

```cpp
namespace std {
  template<class T, class Container = vector<T>,
           class Compare = less<typename Container::value_type>>
  class priority_queue {
  public:
    // ... existing members ...
    constexpr void pop();
    
    constexpr void clear() noexcept(noexcept(c.clear())) 
      requires requires { c.clear(); } 
    { 
      c.clear(); 
    }
  };
} 
```

:::wording-add

Modify <ins>[stack.defn]</ins> (Stack definition):

:::

```cpp
namespace std {
  template<class T, class Container = deque<T>>
  class stack {
  public:
    // ... existing members ...
    constexpr void pop() { c.pop_back(); }
    
    constexpr void clear() noexcept(noexcept(c.clear())) 
      requires requires { c.clear(); } 
    { 
      c.clear(); 
    }
  };
} 

```