命名空间
变体
操作

std::format_to

来自 cppreference.com
< cpp‎ | utility‎ | format
 
 
实用程序库
语言支持
类型支持 (基本类型, RTTI)
库特性测试宏 (C++20)
动态内存管理
程序实用程序
协程支持 (C++20)
可变参数函数
调试支持
(C++26)
三元比较
(C++20)
(C++20)(C++20)(C++20)
(C++20)(C++20)(C++20)
通用实用程序
日期和时间
函数对象
格式化库 (C++20)
(C++11)
关系运算符 (C++20 中已弃用)
整数比较函数
(C++20)(C++20)(C++20)   
(C++20)
交换类型操作
(C++14)
(C++11)
(C++11)
(C++11)
(C++17)
通用词汇类型
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++23)
基本字符串转换
(C++17)
(C++17)

 
 
定义在头文件 <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,

                    std::format_string<Args...> fmt, Args&&... args );
(3) (自 C++20 起)
template< class OutputIt, class... Args >

OutputIt format_to( OutputIt out, const std::locale& loc,

                    std::wformat_string<Args...> fmt, Args&&... args );
(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_argsstd::make_wformat_args 所需)。否则,行为未定义。

内容

[编辑] 参数

out - 指向输出缓冲区的迭代器
fmt - 表示格式字符串的对象。格式字符串由以下组成:
  • 普通字符(除 {} 外),这些字符将原样复制到输出中,
  • 转义序列 {{}},它们在输出中分别替换为 {},以及
  • 替换字段。

每个替换字段具有以下格式:

{ arg-id (可选) } (1)
{ arg-id (可选) : format-spec } (2)
1) 不带格式规范的替换字段
2) 带有格式规范的替换字段
arg-id - 指定 args 中要用于格式化的参数的索引;如果省略,则按顺序使用参数。

格式字符串中的 arg-id  必须全部存在或全部省略。混合使用手动和自动索引会导致错误。

format-spec - 由对应参数的 std::formatter 特化定义的格式规范。不能以 } 开头。

(自 C++23 起)
(自 C++26 起)
  • 对于其他可格式化的类型,格式规范由用户定义的 formatter 特化决定。
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)
将参数的格式化表示形式存储在新的字符串中
(函数模板) [编辑]
通过输出迭代器写入其参数的格式化表示形式,但不超过指定大小
(函数模板) [编辑]