# std::basic_string<CharT,Traits,Allocator>::reserve

From cppreference.com
< cpp‎ | string‎ | basic string

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

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 shrink-to-fit request equivalent to shrink_to_fit() (since C++11). | (until C++20)
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

(none)

### 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).

### Complexity

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

### Example

Run this code

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

    int main()
    {
        std::string s;
        const std::string::size_type new_capacity{100u};
        std::cout << "Before: " << s.capacity() << '\n';

        s.reserve(new_capacity);
        std::cout << "After:  " << s.capacity() << '\n';
        assert(new_capacity <= s.capacity());

        // 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 << "New capacity: " << cap << '\n';
        }

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

Possible output:

    Before: 15
    After:  100
    New capacity: 200
    New capacity: 400
    New capacity: 800
    New capacity: 1600
    After:  801

### Defect reports

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

DR | Applied to | Behavior as published | Correct behavior
--- | --- | --- | ---
LWG 847 | C++98 | there was no exception safety guarantee | 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)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/reserve&oldid=152697"