Namespaces
Variants

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

From cppreference.net
C++
Strings library
std::basic_string
(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++20)
(удалено в C++26)
1) Уведомляет объект std::basic_string о планируемом изменении размера, чтобы он мог соответствующим образом управлять выделением памяти.
  • Если new_cap превышает текущую capacity() , выделяется новая память, и capacity() становится равной или больше new_cap .
  • Если new_cap меньше текущей capacity() , это необязательный запрос на сокращение.
  • Если new_cap меньше текущего size() , это необязательный запрос на сокращение до минимального размера эквивалентный shrink_to_fit() (since C++11) .
(until C++20)
  • Если new_cap меньше или равна текущей capacity() , эффекта нет.
(since 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) Изначально: " << s.capacity() << '\n';
    const std::string::size_type new_cap{101u};
    s.reserve(new_cap);
    assert(s.capacity() >= new_cap);
    std::cout << "2) После reserve(" << new_cap << "): " << s.capacity() << '\n';
    // наблюдение за коэффициентом роста capacity
    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(); // устарело/удалено в C++20/26, используйте:
    s.shrink_to_fit();
    std::cout << "7) После shrink_to_fit: " << s.capacity() << '\n';
}

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

1) Изначально: 15
2) После reserve(101): 101
3) Capacity: 202
4) Capacity: 404
5) Capacity: 808
6) Capacity: 1616
7) После shrink_to_fit: 809

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

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

DR Applied to Behavior as published Correct behavior
LWG 847 C++98 не было гарантии безопасности исключений добавлена строгая гарантия безопасности исключений

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

возвращает количество символов, которое может содержаться в текущем выделенном хранилище
(public member function)
изменяет количество хранимых символов
(public member function)