std::basic_string<CharT,Traits,Allocator>::reserve — cppreference.com

Материал из cppreference.com

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

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;
    const std::string::size_type new_capacity{100u};
    std::cout << "Перед: " << s.capacity() << '\n';
    
    s.reserve(new_capacity);
    std::cout << "После:  " << s.capacity() << '\n';
    assert(new_capacity <= s.capacity());
    
    // наблюдение коэффициента роста ёмкости
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << "Новая ёмкость: " << cap << '\n';
    }
    
    // s.reserve(); // не рекомендуется в C++20, используйте:
    s.shrink_to_fit();
    std::cout << "После:  " << s.capacity() << '\n';
}

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

Перед: 15
После:  100
Новая ёмкость: 200
Новая ёмкость: 400
Новая ёмкость: 800
Новая ёмкость: 1600
После:  801

Отчёты о дефектах

Следующие изменения поведения были применены с обратной силой к ранее опубликованным стандартам C++:

Номер	Применён	Поведение в стандарте	Корректное поведение
LWG 847	C++98	не было гарантии безопасности исключений	добавлена надёжная гарантия безопасности исключений

Смотрите также

	возвращает количество символов, которые могут храниться в выделенной в данный момент памяти (public функция-элемент) [править]
	изменяет количество сохранённых символов (public функция-элемент) [править]

Категории: