命名空间
变体
操作

std::format_to_n, std::format_to_n_result

来自 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 >

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&> 的语义要求),或者如果 std::formatter<std::remove_cvref_t<Ti>, CharT> 对于 Args 中的任何 Ti 不满足 BasicFormatter 要求,则行为未定义。

5) std::format_to_n_result 没有基类,也没有除 outsize 和隐式声明的特殊成员函数之外的成员。

内容

[编辑] 参数

out - 指向输出缓冲区的迭代器
n - 要写入缓冲区的最大字符数
fmt - 一个表示格式字符串的对象。格式字符串由以下组成:
  • 普通字符(除了 {}),它们会被原样复制到输出中;
  • 转义序列 {{}},它们分别替换为输出中的 {};以及
  • 替换字段。

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

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

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

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

(自 C++23 起)
(自 C++26 起)
  • 对于其他可格式化的类型,格式规范由用户定义的 formatter 特化确定。
args... - 要格式化的参数
loc - std::locale 用于特定于区域设置的格式化

[编辑] 返回值

一个 format_to_n_result,其 out 成员是输出范围的末尾迭代器,size 成员是总(未截断)输出大小。

[编辑] 异常

传播格式化程序或迭代器操作引发的任何异常。

[编辑] 注释

在 GCC-13.3 之前,libstdc++ 实现存在 错误,无法报告正确的 format_to_n_result::out 值。

[编辑] 示例

在 Godbolt 的编译器资源管理器中:clang(主干)+ libc++GCC(主干)+ 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++ 标准。

DR 应用于 已发布的行为 正确行为
P2216R3 C++20 对于无效的格式字符串,会抛出 std::format_error 无效的格式字符串会导致编译时错误
P2418R2 C++20 既不可用作常量也不可复制的对象
(例如生成器类对象) 不可格式化
允许格式化这些对象
P2508R1 C++20 此功能没有用户可见的名称 暴露了 basic_format_string 名称

[编辑] 另请参阅

(C++20)
将参数的格式化表示存储在新的字符串中
(函数模板) [编辑]
(C++20)
通过输出迭代器写入其参数的格式化表示
(函数模板) [编辑]
确定存储其参数的格式化表示所需的角色数
(函数模板) [编辑]