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

void reserve( size_type new_cap = 0 );	(1)	(до C++20)
constexpr void reserve( size_type new_cap );	(1)		(начиная с C++20)
void reserve();	(2)	(начиная с C++20) (устарело в 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/cpp/string/basic_string/reserve