Namespaces
Variants

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

    来自 zh.cppreference.net
     
    C++
     
    字符串库
     
    std::basic_string
     
    void reserve( size_type new_cap = 0 );
    		(1) (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()(C++11 起)。
    		 (C++20 前)
    • 如果 new_cap 小于或等于当前 capacity()，则没有效果。
    		 (C++20 起)
    如果发生容量变化，所有迭代器和引用（包括尾后迭代器）都会失效。
    2) 一个非强制性的收缩至合适请求。在此调用之后，capacity() 的值是一个未指定的、大于或等于 size() 的值。

    参数

    new_cap - 字符串的新容量

    返回值

    (无)

    异常

    若 new_cap 大于 max_size() ，则抛出 std::length_error 。

    可能抛出由 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';
    // 观察容量增长因子
    auto cap{s.capacity()};
    for (int check{}; check != 4; ++check)
    {
        while (cap == s.capacity())
            s += '$';
        cap = s.capacity();
        std::cout << (3) + check << ") 容量: " << 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) 容量: 202
4) 容量: 404
5) 容量: 808
6) 容量: 1616
7) 调用 shrink_to_fit 后: 809

    缺陷报告

    以下行为变更缺陷报告被追溯应用于先前发布的C++标准。

    DR 适用范围 发布时的行为 正确行为
    LWG 847 C++98 未提供异常安全保证 增加了强异常安全保证

    参见

    		返回当前分配存储中可容纳的字符数量
    (公开成员函数)
    		更改存储的字符数量
    (公开成员函数)