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

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());
}

Language
Standard Library Headers
Freestanding and hosted implementations
Named requirements
Language support library
Concepts library (C++20)
Diagnostics library
Utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Input/output library
Localizations library
Regular expressions library (C++11)
Atomic operations library (C++11)
Thread support library (C++11)
Filesystem library (C++17)
Technical Specifications