std::format_to_n, std::format_to_n_result
在头文件 <format> 中定义 |
||
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> |
(1) | (自 C++20 起) |
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> |
(2) | (自 C++20 起) |
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> |
(3) | (自 C++20 起) |
template< class OutputIt, class... Args > std::format_to_n_result<OutputIt> |
(4) | (自 C++20 起) |
辅助类型 |
||
template< class OutputIt > struct format_to_n_result { |
(5) | (自 C++20 起) |
根据格式字符串 fmt 格式化 args,并将结果写入输出迭代器 out。最多写入 n 个字符。如果存在,则 loc 用于特定于区域设置的格式化。
令 CharT
为重载 (1,3) 的 char,重载 (2,4) 的 wchar_t。
仅当 OutputIt
满足概念 std::output_iterator<const CharT&> 时,这些重载才参与重载解析。
如果 OutputIt
不建模(不满足 std::output_iterator<const CharT&> 的语义要求),或者如果 std::formatter<std::remove_cvref_t<Ti>, CharT> 对于 Args
中的任何 Ti
不满足 BasicFormatter 要求,则行为未定义。
std::format_to_n_result
没有基类,也没有除 out、size
和隐式声明的特殊成员函数之外的成员。内容 |
[编辑] 参数
out | - | 指向输出缓冲区的迭代器 | ||||||||||||||||||||||||||||||||||||||||||||||
n | - | 要写入缓冲区的最大字符数 | ||||||||||||||||||||||||||||||||||||||||||||||
fmt | - |
每个替换字段都具有以下格式:
1) 没有格式规范的替换字段
2) 有格式规范的替换字段
| ||||||||||||||||||||||||||||||||||||||||||||||
args... | - | 要格式化的参数 | ||||||||||||||||||||||||||||||||||||||||||||||
loc | - | std::locale 用于特定于区域设置的格式化 |
[编辑] 返回值
一个 format_to_n_result
,其 out 成员是输出范围的末尾迭代器,size
成员是总(未截断)输出大小。
[编辑] 异常
传播格式化程序或迭代器操作引发的任何异常。
[编辑] 注释
在 GCC-13.3 之前,libstdc++ 实现存在 错误,无法报告正确的 format_to_n_result::out 值。
[编辑] 示例
在 Godbolt 的编译器资源管理器中:clang(主干)+ libc++,GCC(主干)+ libstdc++。
#include <format> #include <initializer_list> #include <iomanip> #include <iostream> #include <string_view> int main() { char buffer[64]; for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz}) { const std::format_to_n_result result = std::format_to_n( buffer, max_chars_to_write, "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters 71, // {0}, occupies 2 bytes 8, // {1}, occupies 1 byte "\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO) "\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO) "\u00B1" // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN) ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0' *result.out = '\0'; // adds terminator to buffer const std::string_view str(buffer, result.out); std::cout << "Buffer until '\\0': " << std::quoted(str) << '\n' << "Max chars to write: " << max_chars_to_write << '\n' << "result.out offset: " << result.out - buffer << '\n' << "Untruncated output size: " << result.size << "\n\n"; } }
输出
Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc." Max chars to write: 63 result.out offset: 35 Untruncated output size: 35 Buffer until '\0': "Hubble's H₀ ≅ 71±8" Max chars to write: 23 result.out offset: 23 Untruncated output size: 35 Buffer until '\0': "Hubble's H₀ ≅ 71�" Max chars to write: 21 result.out offset: 21 Untruncated output size: 35
[编辑] 缺陷报告
以下更改行为的缺陷报告已追溯应用于先前发布的 C++ 标准。
DR | 应用于 | 已发布的行为 | 正确行为 |
---|---|---|---|
P2216R3 | C++20 | 对于无效的格式字符串,会抛出 std::format_error | 无效的格式字符串会导致编译时错误 |
P2418R2 | C++20 | 既不可用作常量也不可复制的对象 (例如生成器类对象) 不可格式化 |
允许格式化这些对象 |
P2508R1 | C++20 | 此功能没有用户可见的名称 | 暴露了 basic_format_string 名称 |
[编辑] 另请参阅
(C++20) |
将参数的格式化表示存储在新的字符串中 (函数模板) |
(C++20) |
通过输出迭代器写入其参数的格式化表示 (函数模板) |
(C++20) |
确定存储其参数的格式化表示所需的角色数 (函数模板) |