Namespaces
Variants

std:: format_to_n, std:: format_to_n_result

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
format_to_n
(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 >

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,
const std:: locale & loc,

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,
const std:: locale & loc,

std:: wformat_string < Args... > fmt, Args && ... args ) ;
(4) (C++20 起)
辅助类型
template < class OutputIt >

struct format_to_n_result {
OutputIt out ;
std:: iter_difference_t < OutputIt > size ;

} ;
(5) (C++20 起)

按照格式字符串 fmt 格式化 args ，并将结果写入输出迭代器 out 。最多写入 n 个字符。如果存在 loc ，则将其用于区域设置特定的格式化。

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

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

若 OutputIt 不满足 std:: output_iterator < const CharT & > 概念（即不符合其语义要求），或对于 Args 中的任意 Ti ， std:: formatter < std:: remove_cvref_t < Ti > , CharT > 不满足 BasicFormatter 要求，则行为未定义。

5) std::format_to_n_result 没有基类，除 out 、 size 以及隐式声明的特殊成员函数外没有其他成员。

目录

参数

out - 指向输出缓冲区的迭代器
n - 要写入缓冲区的最大字符数
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

返回值

一个 format_to_n_result 对象，其 out 成员是指向输出范围末尾之后位置的迭代器，而 size 成员是总（未截断的）输出大小。

异常

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

注释

GCC-13.3 之前的 libstdc++ 实现在报告正确的 format_to_n_result :: out 值时存在一个 缺陷 。

示例

在 Godbolt 的 Compiler Explorer 上： clang (trunk) + libc++ ， GCC (trunk) + libstdc++ 。

运行此代码 
#include <format>
#include <initializer_list>
#include <iomanip>
#include <iostream>
#include <string_view>
int main()
{
    char buffer[64];
    for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz})
    {
        const std::format_to_n_result result =
            std::format_to_n(
                buffer, max_chars_to_write,
                "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters
                71,       // {0}, occupies 2 bytes
                8,        // {1}, occupies 1 byte
                "\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)
                "\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)
                "\u00B1"  // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN)
                ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0'
        *result.out = '\0'; // adds terminator to buffer
        const std::string_view str(buffer, result.out);
        std::cout << "Buffer until '\\0': " << std::quoted(str) << '\n'
                  << "Max chars to write: " << max_chars_to_write << '\n'
                  << "result.out offset: " << result.out - buffer << '\n'
                  << "Untruncated output size: " << result.size << "\n\n";
    }
}

输出： 

Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc."
Max chars to write: 63
result.out offset: 35
Untruncated output size: 35
Buffer until '\0': "Hubble's H₀ ≅ 71±8"
Max chars to write: 23
result.out offset: 23
Untruncated output size: 35
Buffer until '\0': "Hubble's H₀ ≅ 71�"
Max chars to write: 21
result.out offset: 21
Untruncated output size: 35

缺陷报告

下列行为变更缺陷报告被追溯应用于先前发布的 C++ 标准。

缺陷报告 应用于 发布时行为 正确行为
P2216R3 C++20 对无效格式字符串抛出 std::format_error 无效格式字符串导致编译时错误
P2418R2 C++20 既非常量可用也非可复制的对象
（如生成器类对象）不可格式化 		允许格式化这些对象
P2508R1 C++20 该设施没有对用户可见的名称 公开 basic_format_string 名称

参见

(C++20)
将参数的格式化表示存储到新字符串中
(函数模板)
(C++20)
通过输出迭代器写出参数的格式化表示
(函数模板)
(C++20)
确定存储参数格式化表示所需的字符数量
(函数模板)