std::basic_string<CharT,Traits,Allocator>::reserve
From cppreference.com
< cpp | string | basic string
C++
Feature test macros (C++20)
Concepts library (C++20)
Metaprogramming library (C++11)
Ranges library (C++20)
Filesystem library (C++17)
Concurrency support library (C++11)
Execution control library (C++26)
std::basic_string
Literals Helper classes Deduction guides (C++17)
(C++23)
(DR*)
(DR*)
(C++23)
(DR*)
(C++23)
(C++23)
basic_string::reserve
(C++20)
(C++20)
(C++23)
(C++20)(C++20)
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++14)
(C++11)
(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 in C++20)
(removed in C++26)
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).
- If new_cap is less than or equal to the current capacity() , there is no effect.
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() .
Contents
[edit] Parameters
new_cap
-
new capacity of the string
[edit] Return value
(none)
[edit] 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).
[edit] Complexity
At most linear in the size() of the string.
[edit] Example
Run this code
#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
[edit] 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 |
[edit] See also
returns the number of characters that can be held in currently allocated storage
(public member function) [edit]
(public member function) [edit]