std::format_to
来自 cppreference.cn
定义于头文件 <format> |
||
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, |
(1) | (C++20 起) |
template< class OutputIt, class... Args > OutputIt format_to( OutputIt out, |
(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(std::move(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(std::move(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...));。
对于重载 (1,3),令 CharT
为 char;对于重载 (2,4),令 CharT
为 wchar_t。
这些重载仅当 OutputIt
满足概念 std::output_iterator<const CharT&> 时才参与重载决议。
如果满足以下任何条件,则行为是未定义的:
-
OutputIt
不符合 std::output_iterator<const CharT&> 模型。 - 对于
Args
中的某些Ti
,std::formatter<Ti, CharT> 不满足 BasicFormatter 要求(如 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++ 标准。
缺陷报告 | 应用于 | 发布时的行为 | 正确的行为 |
---|---|---|---|
LWG 3539 | C++20 | out 不能是仅移动迭代器 | 它可以是 |
P2216R3 | C++20 | 对无效格式字符串抛出 std::format_error | 导致编译时错误 |
P2418R2 | C++20 | 既不可 const 使用也不可复制的对象 (例如生成器类对象) 不可格式化 |
允许格式化这些对象 |
P2508R1 | C++20 | 该功能没有用户可见的名称 | 公开了名称 basic_format_string |
[编辑] 另请参阅
(C++20) |
将参数的格式化表示存储在新字符串中 (函数模板) |
(C++20) |
通过输出迭代器写出其参数的格式化表示,不超过指定大小 (函数模板) |