命名空间
变体
操作

std::format_to

来自 cppreference.cn
< cpp‎ | 工具‎ | 格式化
 
 
 
 
定义于头文件 <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...));


对于重载 (1,3),令 CharTchar;对于重载 (2,4),令 CharTwchar_t

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

如果满足以下任何条件,则行为是未定义的:

目录

[编辑] 参数

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++ 标准。

缺陷报告 应用于 发布时的行为 正确的行为
LWG 3539 C++20 out 不能是仅移动迭代器 它可以是
P2216R3 C++20 对无效格式字符串抛出 std::format_error 导致编译时错误
P2418R2 C++20 既不可 const 使用也不可复制的对象
(例如生成器类对象) 不可格式化
允许格式化这些对象
P2508R1 C++20 该功能没有用户可见的名称 公开了名称 basic_format_string

[编辑] 另请参阅

(C++20)
将参数的格式化表示存储在新字符串中
(函数模板) [编辑]
通过输出迭代器写出其参数的格式化表示,不超过指定大小
(函数模板) [编辑]