std::basic_...ng::capacity(3)

🌸 NAME 🌸

std::basic_string::capacity — literally std::basic_string::capacity, bestie. This is the std::basic_...ng::capacity(3) page from the C++ Standard Libary (manual name, yes, that spelling is the manual name, iykyk 🫶).

✨ Synopsis ✨

size_type capacity() const;  (noexcept since C++11)
                             (constexpr since C++20)

Returns the number of characters that the string has currently allocated space for. That's the whole vibe 💅.

🎀 Parameters 🎀

(none) — zero parameters. Nada. Not a single one, bestie.

💖 Return value 💖

The capacity of the currently allocated storage, i.e. the storage available for storing elements. That's it. That's the return value. Periodt 💫.

🦋 Complexity 🦋

Constant. Zero drama, constant energy, literally.

🌸 Notes 🌸

Okay, important note time: memory locations obtained from the allocator but not available for storing any element are not counted in the allocated storage. Also, note that the null terminator is not an element of the std::basic_string. Not me reminding you about the null terminator 💀.

🔥 Example 🔥

The page says // Run this code — so go run it, bestie 💅

#include <iomanip>
#include <iostream>
#include <string>

void show_capacity(std::string const& s)
{
    std::cout << std::quoted(s) << " has capacity " << s.capacity() <<
        ".\n";
}

int main()
{
    std::string s{"Exemplar"};
    show_capacity(s);

    s += " is an example string.";
    show_capacity(s);

    s.clear();
    show_capacity(s);

    std::cout << "\nDemonstrate the capacity's growth policy."
                 "\nSize:  Capacity:  Ratio:\n" << std::left;

    std::string g;
    auto old_cap{g.capacity()};

    for (int mark{}; mark != 5; ++mark)
    {
        while (old_cap == g.capacity())
            g.push_back('.');

        std::cout << std::setw( 7) << g.size()
                  << std::setw(11) << g.capacity()
                  << std::setw(10) << g.capacity() /
                     static_cast<float>(old_cap) << '\n';

        old_cap = g.capacity();
    }
}

💫 Possible output 💫

"Exemplar" has capacity 15.
"Exemplar is an example string." has capacity 30.
"" has capacity 30.

Demonstrate the capacity's growth policy.
Size:  Capacity:  Ratio:
16     30         2
31     60         2
61     120        2
121    240        2
241    480        2

👑 See also 👑

• size — returns the number of characters
• length — (public member function)
• reserve — reserves storage (public member function)

Source/version: http://cppreference.com 🌈 Page date: 2024.06.10 ⭐ Footer title: std::basic_...ng::capacity(3) 🎀 Bye bestie, go check that capacity 💖