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

	(1)
void reserve( size_type new_cap = 0 );			(until C++20)
constexpr void reserve( size_type new_cap );			(since C++20)
void reserve();		(2)	(since C++20) (deprecated in C++20) (removed in 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

-

字符串的新容量

[编辑] 返回值

(无)

[编辑] 异常

如果 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) 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	更改存储的字符数 (公共成员函数) [编辑]

编译器支持
独立和托管
语言
标准库
标准库头文件
命名要求
特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用实用程序库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
执行支持库 (C++26)
技术规范
符号索引
外部库

以空字符结尾的字符串
字节字符串
多字节字符串
宽字符字符串
类
basic_string
basic_string_view (C++17)
char_traits

cppreference.com

命名空间

变体

视图

操作