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

	(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）请求，等价于 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++ 标准。

缺陷报告	应用于	出版时的行为	正确行为
LWG 847	C++98	没有异常安全保证	添加强异常安全保证

参阅

capacity	返回当前对象分配的存储空间能保存的字符数量 (公开成员函数)
resize	更改存储的字符数 (公开成员函数)

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

空终止字符串
字节字符串
多字节字符串
宽字符串
类
basic_string
basic_string_view (C++17)
char_traits

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

参数

返回值

异常

复杂度

示例

缺陷报告

参阅

导航