std::format_to
来自 cppreference.com
定义在头文件 <format> 中 |
||
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, std::format_string<Args...> fmt, Args&&... args ); |
(1) | (自 C++20 起) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, std::wformat_string<Args...> fmt, Args&&... args ); |
(2) | (自 C++20 起) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc, |
(3) | (自 C++20 起) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, const std::locale& loc, |
(4) | (自 C++20 起) |
根据格式字符串 fmt 格式化 args,并将结果写入输出迭代器 out。如果存在,则 loc 用于特定于区域设置的格式化。
等效于
1) return std::vformat_to(out, fmt.str, std::make_format_args(args...));
2) return std::vformat_to(std::move(out), fmt.str, std::make_wformat_args(args...));
3) return std::vformat_to(out, loc, fmt.str, std::make_format_args(args...));
4) return std::vformat_to(std::move(out), loc, fmt.str, std::make_wformat_args(args...));.
令 CharT
为重载 (1,3) 的 char,重载 (2,4) 的 wchar_t。
这些重载仅当 OutputIt
满足概念 std::output_iterator<const CharT&> 时才参与重载解析。
OutputIt
必须建模(满足概念的语义要求)std::output_iterator<const CharT&>,并且 std::formatter<Ti, CharT> 必须满足 BasicFormatter 要求,用于 Args
中的任何 Ti
(如 std::make_format_args 和 std::make_wformat_args 所需)。否则,行为未定义。
内容 |
[编辑] 参数
out | - | 指向输出缓冲区的迭代器 | ||||||||||||||||||||||||||||||||||||||||||||||
fmt | - |
每个替换字段具有以下格式:
1) 不带格式规范的替换字段
2) 带有格式规范的替换字段
| ||||||||||||||||||||||||||||||||||||||||||||||
args... | - | 要格式化的参数 | ||||||||||||||||||||||||||||||||||||||||||||||
loc | - | std::locale 用于特定于区域设置的格式化 |
[编辑] 返回值
输出范围末尾之后的迭代器。
[编辑] 异常
传播格式化程序或迭代器操作抛出的任何异常。
[编辑] 备注
截至 P2216R3,如果格式字符串不是常量表达式,则会发生错误。在这种情况下,可以使用 std::vformat_to 或 std::runtime_format(自 C++26 起)。
[编辑] 示例
运行此代码
#include <format> #include <iostream> #include <iterator> #include <string> int main() { std::string buffer; std::format_to( std::back_inserter(buffer), //< OutputIt "Hello, C++{}!\n", //< fmt "20"); //< arg std::cout << buffer; buffer.clear(); std::format_to( std::back_inserter(buffer), //< OutputIt "Hello, {0}::{1}!{2}", //< fmt "std", //< arg {0} "format_to()", //< arg {1} "\n", //< arg {2} "extra param(s)..."); //< unused std::cout << buffer << std::flush; std::wstring wbuffer; std::format_to( std::back_inserter(wbuffer),//< OutputIt L"Hello, {2}::{1}!{0}", //< fmt L"\n", //< arg {0} L"format_to()", //< arg {1} L"std", //< arg {2} L"...is not..." //< unused L"...an error!"); //< unused std::wcout << wbuffer; }
输出
Hello, C++20! Hello, std::format_to()! Hello, std::format_to()!
[编辑] 缺陷报告
以下更改行为的缺陷报告已追溯应用于以前发布的 C++ 标准。
DR | 应用于 | 已发布的行为 | 正确行为 |
---|---|---|---|
P2216R3 | C++20 | 对于无效的格式字符串,抛出 std::format_error | 无效的格式字符串会导致编译时错误 |
P2418R2 | C++20 | 既不可使用常量也不可复制的对象 (例如类似生成器的对象) 不可格式化 |
允许格式化这些对象 |
P2508R1 | C++20 | 此功能没有用户可见的名称 | 公开名称 basic_format_string |
[编辑] 另请参阅
(C++20) |
将参数的格式化表示形式存储在新的字符串中 (函数模板) |
(C++20) |
通过输出迭代器写入其参数的格式化表示形式,但不超过指定大小 (函数模板) |