std::deque::shrink_to_fit(3)

✨ NAME ✨

std::deque::shrink_to_fit — the whole manual page for this iconic little member function, from the C++ Standard Libary manual, section (3). Yes, bestie, this is literally the std::deque::shrink_to_fit(3) page, and we are folding that header energy right here at the top. 💅

🌸 Synopsis 🌸

void shrink_to_fit();

It requests the removal of unused capacity. That's the whole plot. 🎀

It is a non-binding request to reduce the memory usage without changing the size of the sequence. It depends on the implementation whether the request is fulfilled — so don't @ it if memory doesn't shrink, it's literally allowed to ignore you. 😭

All iterators (including the end() iterator) and references are invalidated. Not a vibe, bestie: your iterators and references are gone-gone. 💀

🎀 Parameters 🎀

(none) — literally zero parameters. Nothing to pass, nothing to stress about. 🫶

💖 Type requirements 💖

• T must meet the requirements of MoveInsertable into *this. (since C++11)

⭐ Return value ⭐

(none) — it returns nothing. It's giving "I did the thing, or maybe I didn't, no receipts." ✨

🔥 Complexity 🔥

At most linear in the size of the container. So, like, <= linear, bestie. 🔥

😭 Exceptions 😭

(since C++11)

If an exception is thrown other than by the move constructor of a non-CopyInsertable T, there are no effects. 🫡

🧚 Notes 🧚

In libstdc++, shrink_to_fit() is not available in C++98 mode. That's the whole note, no cap. 💜

✨ Example ✨

// Run this code — yes, that's the cue, go run it:

#include <cstddef>
#include <deque>
#include <iostream>
#include <new>

// Minimal C++11 allocator with debug output.
template<class Tp>
struct NAlloc
{
    typedef Tp value_type;

    NAlloc() = default;

    template<class T> NAlloc(const NAlloc<T>&) {}

    Tp* allocate(std::size_t n)
    {
        n *= sizeof(Tp);
        std::cout << "allocating " << n << " bytes\n";
        return static_cast<Tp*>(::operator new(n));
    }

    void deallocate(Tp* p, std::size_t n)
    {
        std::cout << "deallocating " << n*sizeof*p << " bytes\n";
        ::operator delete(p);
    }
};
template<class T, class U>
bool operator==(const NAlloc<T>&, const NAlloc<U>&) { return true; }
template<class T, class U>
bool operator!=(const NAlloc<T>&, const NAlloc<U>&) { return false; }

int main()
{
    // std::queue has no capacity() function (like std::vector).
    // Because of this, we use a custom allocator to show the
    // working of shrink_to_fit.

    std::cout << "Default-construct deque:\n";
    std::deque<int, NAlloc<int>> deq;

    std::cout << "\nAdd 300 elements:\n";
    for (int i = 1000; i < 1300; ++i)
        deq.push_back(i);

    std::cout << "\nPop 100 elements:\n";
    for (int i = 0; i < 100; ++i)
        deq.pop_front();

    std::cout << "\nRun shrink_to_fit:\n";
    deq.shrink_to_fit();

    std::cout << "\nDestroy deque as it goes out of scope:\n";
}

🍓 Possible output: 🍓

Default-construct deque:
allocating 64 bytes
allocating 512 bytes

Add 300 elements:
allocating 512 bytes
allocating 512 bytes

Pop 100 elements:

Run shrink_to_fit:
allocating 64 bytes
allocating 512 bytes
allocating 512 bytes
deallocating 512 bytes
deallocating 512 bytes
deallocating 512 bytes
deallocating 64 bytes

Destroy deque as it goes out of scope:
deallocating 512 bytes
deallocating 512 bytes
deallocating 64 bytes

💀 Defect reports 💀

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 850 — applied to C++98. Behavior as published: std::deque lacked explicit shrink-to-fit operations. Correct behavior: provided.
• LWG 2033 — applied to C++11. Behavior as published: 1. T was not required to be MoveInsertable; 2. the complexity requirement was missing. Correct behavior: 1. required; 2. added.

🌈 See also 🌈

• size — returns the number of elements (public member function).

---

Okay bestie, that's the whole page. Source: http://cppreference.com; version/date: 2024.06.10; manual: std::deque::shrink_to_fit(3). Stay hydrated and don't invalidate your iterators. 💖🫶🎀