std::basic_string<CharT,Traits,Allocator>::reserve - cppreference.com (original) (raw)

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 a capacity change takes place, all iterators and references, including the past-the-end iterator, are invalidated.

1. A non-binding shrink-to-fit request. After this call, capacity() has an unspecified value greater than or equal to size().

Contents

• 1 Parameters
• 2 Return value
• 3 Exceptions
• 4 Complexity
• 5 Example
• 6 Defect reports
• 7 See also

[edit] Parameters

[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

#include #include #include   int main() { std::string s; std::cout << "1) Initially: " << s.capacity() << '\n';   const std:🧵: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.

[edit] See also

| | returns the number of characters that can be held in currently allocated storage (public member function) [edit] | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | changes the number of characters stored (public member function) [edit] |