Namespaces
Variants

std:: format_to

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
format_to
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20) (C++20) (C++20)
(C++20) (C++20) (C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
(C++20)
(C++20) (C++20) (C++20)
(C++20) (deprecated in C++26)
(C++20) (C++20)
Format error
(C++20)
定义于头文件 <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 ( 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... ) ) ; .


令 CharT 对于重载 (1,3) 为 char ，对于重载 (2,4) 为 wchar_t 。

这些重载仅当 OutputIt 满足概念 std:: output_iterator < const CharT & > 时参与重载决议。

若满足以下任一条件，则行为未定义：

目录

参数

out - 输出缓冲区的迭代器
fmt -
表示格式字符串的对象。格式字符串包含：
  • 普通字符（除了 { 和 } ），它们会原样复制到输出，
  • 转义序列 { { 和 } } ，它们在输出中分别被替换为 { 和 } ，以及
  • 替换字段。

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

{ arg-id (optional) } (1)
{ arg-id (optional) : format-spec } (2)
1) 不带格式说明的替换字段
2) 带格式说明的替换字段
arg-id - 指定 args 中参数的索引，其值将用于格式化；如果省略，则按顺序使用参数。

格式字符串中的 arg-id 必须全部显式指定或全部省略。混合手动和自动索引是错误的。

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

(since C++23)
(since C++26)
  • 对于其他可格式化类型，格式规范由用户定义的 formatter 特化决定。
args... - 要格式化的参数
loc - 用于本地化格式化的 std::locale

返回值

输出范围末尾之后的迭代器。

异常

传播由格式化器或迭代器操作抛出的任何异常。

注释

如果格式字符串不是常量表达式，则会产生错误 除非它是从 std::runtime_format 的结果初始化而来 (since C++26) 。 std::vformat_to 则无此要求。

示例

运行此代码 
#include <format>
#include <iostream>
#include <iterator>
#include <string>
int main()
{
    std::string buffer;
    std::format_to
    (
        std::back_inserter(buffer), // < 输出迭代器
        "Hello, C++{}!\n",          // < 格式字符串
        "20"                        // < 参数
    );
    std::cout << buffer;
    buffer.clear();
    std::format_to
    (
        std::back_inserter(buffer), // < 输出迭代器
        "Hello, {0}::{1}!{2}",      // < 格式字符串
        "std",                      // < 参数 {0}
        "format_to()",              // < 参数 {1}
        "\n",                       // < 参数 {2}
        "extra param(s)..."         // < 未使用参数
    );
    std::cout << buffer << std::flush;
    std::wstring wbuffer;
    std::format_to
    (
        std::back_inserter(wbuffer),// < 输出迭代器
        L"Hello, {2}::{1}!{0}",     // < 格式字符串
        L"\n",                      // < 参数 {0}
        L"format_to()",             // < 参数 {1}
        L"std",                     // < 参数 {2}
        L"...is not..."             // < 未使用参数
        L"...an error!"             // < 未使用参数
    );
    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 既不能常量使用也不能复制的对象
（如生成器类对象）不可格式化 		允许格式化这些对象
P2508R1 C++20 该功能没有对用户可见的名称 公开了 basic_format_string 名称

参见

(C++20)
将参数的格式化表示存储到新字符串中
(函数模板)
(C++20)
通过输出迭代器写入参数的格式化表示，不超过指定大小
(函数模板)