std::basic_string::reserve(3)

Bestie, welcome to the C++ Standard Libary manual — yes, that's the header's spelling, not me 😭 — and we're on the std::basic_string::reserve(3) page. Buckle up, this one's lowkey about storage glow-ups ✨

🎀 NAME 🎀

std::basic_string::reserve — std::basic_string::reserve — that's the whole name, bestie 💅

✨ Synopsis ✨

Here's the signature timeline, no cap:

void reserve( size_type new_cap = 0 );               (until C++20)
constexpr void reserve( size_type new_cap );         (since C++20)
                                                     (1)     (since C++20)
void reserve();                                  (2) (deprecated in
C++20)
                                                             (removed in
C++26)

The (1) and (2) markers are overload labels, bestie — don't let the spacing gaslight you 🫶

Okay so here's the actual tea ☕

• 1) Informs a std::basic_string object of a planned change in size, so that it can manage the storage allocation appropriately.
  • If new_cap is greater than the current capacity(), new storage is allocated, and capacity() is made equal or greater than new_cap.
  • If new_cap is less than the current capacity(), this is a non-binding shrink request.
  • If new_cap is less than the current size(), this is a non-binding (until C++20) shrink-to-fit request equivalent to shrink_to_fit() (since C++11).
  • If new_cap is less than or equal to the current capacity(), there is no effect. (since C++20)
• If a capacity change takes place, all iterators and references, including the past-the-end iterator, are invalidated.
• 2) A non-binding shrink-to-fit request. After this call, capacity() has an unspecified value greater than or equal to size().

🌸 Parameters 🌸

• new_cap — new capacity of the string.

🫶 Return value 🫶

Literally (none), bestie. It's giving "I did the work, I don't need a trophy" 💅

😭 Exceptions 😭

• Throws std::length_error if new_cap is greater than max_size().
• May throw any exceptions thrown by std::allocator_traits<Allocator>::allocate(), such as std::bad_alloc.
• If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee). Iconic behavior, honestly ✨

⚡ Complexity ⚡

At most linear in the size() of the string.

💻 Example 💻

// Run this code — yes bestie, run it:

#include <cassert>
#include <iostream>
#include <string>

int main()
{
    std::string s;
    std::cout << "1) Initially: " << s.capacity() << '\n';

    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) After reserve(" << new_cap << "): " << s.capacity() << '\n';

    // observing the capacity growth factor
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << (3) + check << ") Capacity: " << cap << '\n';
    }

//  s.reserve(); // deprecated/removed in C++20/26, use:
    s.shrink_to_fit();
    std::cout << "7) After shrink_to_fit: " << s.capacity() << '\n';
}

💀 Possible output 💀

1) Initially: 15
2) After reserve(101): 101
3) Capacity: 202
4) Capacity: 404
5) Capacity: 808
6) Capacity: 1616
7) After shrink_to_fit: 809

🧚 Defect reports 🧚

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

• LWG 847 — applied to C++98; behavior as published: there was no exception safety guarantee; correct behavior: added strong exception safety guarantee.

👑 See also 👑

• capacity — returns the number of characters that can be held in currently allocated storage (public member function).
• resize — changes the number of characters stored (public member function).

---

Source/version/date check, bestie: http://cppreference.com, 2024.06.10, page std::basic_string::reserve(3) — and that's the whole manual page, periodt 💖✨🦋