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

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

void reserve( size_type new_cap = 0 ); | (1) | (until C++20)
void reserve( size_type new_cap); | (1) | (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 call to `reserve` with no argument is a non-binding shrink-to-fit request. After this call, capacity() has an unspecified value greater than or equal to size(). | (since C++20)

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

### Complexity

At most linear in the size() of the string

### Example

Run this code

    #include <cassert>
    #include <string>

    int main()
    {
        std::string s;
        std::string::size_type new_capacity{ 100u };
        assert(new_capacity > s.capacity());

        s.reserve(new_capacity);
        assert(new_capacity <= s.capacity());
    }

### See also

capacity | returns the number of characters that can be held in currently allocated storage (public member function)

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