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

	(1)
void reserve( size_type new_cap = 0 );		(до C++20)
constexpr void reserve( size_type new_cap );		(с C++20)
void reserve();	(2)	(устарело в C++20) (удалено в C++26)

1) Сообщает объекту std::basic_string о запланированном изменении размера, чтобы он мог соответствующим образом управлять выделением памяти.

Если new_cap больше текущего capacity(), выделяется новая память, и capacity() устанавливается равным или большим new_cap.

Если `new_cap` меньше текущего `capacity()`, это необязательный запрос на уменьшение размера. Если `new_cap` меньше текущего `size()`, это необязательный запрос на сжатие до нужного размера эквивалентный `shrink_to_fit()`(с C++11).	(до C++20)
Если `new_cap` меньше или равно текущему `capacity()`, никакого эффекта нет.	(с C++20)

Если происходит изменение емкости, все итераторы и ссылки, включая итератор за последним элементом, становятся недействительными.

2) Необязательный запрос на сжатие до нужного размера. После этого вызова capacity() имеет неопределенное значение, большее или равное size().

Параметры

new_cap

новая емкость строки

Возвращаемое значение

(нет)

Исключения

Выбрасывает std::length_error если new_cap больше чем max_size().

Может выбросить любые исключения, выброшенные std::allocator_traits<Allocator>::allocate(), такие как std::bad_alloc.

Если исключение выброшено по любой причине, эта функция не оказывает эффекта (гарантия сильной защиты от исключений).

Сложность

Максимум линейная по size() строки.

Пример

#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';
}

Возможный вывод:

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

Отчеты об ошибках

Следующие отчеты об ошибках, изменяющих поведение, были применены ретроактивно к ранее опубликованным стандартам C++.

DR	Применено к	Поведение, как опубликовано	Правильное поведение
LWG 847	C++98	гарантии защиты от исключений не было	добавлен сильная гарантия защиты от исключений

См. также

capacity	возвращает количество символов, которое может храниться в текущем выделенном хранилище (публичный член-функция)
resize	изменяет количество хранимых символов (публичный член-функция)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/string/basic_string/reserve