格式化库 (C++20 起)

< cpp‎ | utility


文本格式化库提供 printf 函数族的安全且可扩展的替用品。其意图是补充既存的 C++ I/O 流库。

格式说明

格式说明制定了对象在不同类别的选项下会如何进行格式化。

基本类型和标准字符串类型对象会使用标准格式说明进行格式化。其他库组件也会提供它们自己的格式说明，详情见此处。

格式化函数

在标头 <format> 定义
(C++20)
 在新字符串中存储参数的格式化表示
(函数模板)
(C++20)
 通过输出迭代器写入其实参的格式化表示
(函数模板)
(C++20)
 通过输出迭代器写入其实参的格式化表示，不超出指定的大小
(函数模板)
(C++20)
 确定存储其参数的格式化表示所需的字符数
(函数模板)

格式字符串

在标头 <format> 定义
(C++20)(C++20)(C++20)
 在构造时执行编译期格式字符串检查的类模板
(类模板)
(C++26)
 创建能直接用于面向用户的格式化函数的运行时格式串
(函数)

格式化概念

在标头 <format> 定义
(C++23)
 指示一个类型可格式化，即它特化了 std::formatter 并且提供了成员函数 parse 和 format
(概念)

扩展性支持与实现细节

在标头 <format> 定义
(C++20)
 std::format 的使用类型擦除的参数表示的非模板变体
(函数)
(C++20)
 std::format_to 的使用类型擦除的参数表示的非模板变体
(函数模板)
(C++20)(C++20)
 创建引用所有格式化参数的类型擦除对象，可转换到 format_args
(函数模板)
(C++20) (C++26 中弃用)
 用户定义格式化器的参数探访接口
(函数模板)
(C++20)
 定义针对给定类型的格式化规则
(类模板)
(C++23)
 用于帮助实现 std::formatter 对范围类型的特化的类模板
(类模板)
(C++23)
 指示实现可以高效打印实参类型
(变量模板)
(C++23)
 指示一个范围应该如何被格式化
(枚举)
(C++23)
 为范围选择合适的 std::range_format
(变量模板)
(C++20)
 提供对用户定义格式化器的格式化参数的访问的类模板
(类模板)
(C++20)(C++20)(C++20)
 提供对所有格式化参数的访问的类
(类模板)
(C++20)(C++20)(C++20)
 格式化状态，包括所有格式化参数和输出迭代器
(类模板)
(C++20)(C++20)(C++20)
 格式化字符串分析器状态
(类模板)
(C++20)
 格式化错误时抛出的异常类型
(类)

辅助项 (C++23 起)

template< class R, class CharT >

concept /*const-formattable-range*/ =
    ranges::input_range<const R> &&

    std::formattable<ranges::range_reference_t<const R>, CharT>;
 (1) (仅用于阐述*)
template< class R, class CharT >

using /*fmt-maybe-const*/ =

    std::conditional_t</*const-formattable-range*/<R, CharT>, const R, R>;
 (2) (仅用于阐述*)

注解

功能特性测试宏 值 标准 功能特性
__cpp_lib_format 201907L (C++20) 文本格式化
202106L (C++20)
(DR)		 编译期格式字符串检查
减少 std::vformat_to 的参数化
202110L (C++20)
(DR)		 修复时间格式化器中的本地化处理；
支持非 const 可格式化类型
202207L (C++23) 暴露 std::basic_format_string；
澄清时间类型的本地化编码处理
202304L (C++26) 格式化指针
202305L (C++26) 对格式化参数进行类型检查
202306L (C++26) std::basic_format_arg::visit 成员
__cpp_lib_format_ranges 202207L (C++23) 格式化范围

我们有意将 std::basic_format_string 的加入（P2508）作为缺陷报告处理，因为所有已知的实现都使这些组件在 C++20 模式下可用，尽管它没有被正式分类。

示例

#include <cassert>
#include <format>
 
int main()
{
    std::string message = std::format("答案是 {}。", 42);
    assert(message == "答案是 42。");
}

缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告 应用于 出版时的行为 正确行为
P2418R2 C++20 既不可 const 格式化又不可复制的对象（例如类生成器对象）不可格式化 允许格式化这些对象（放松格式化器要求）
P2508R1 C++20 这个设施没有用户可见的名字 暴露出 basic_format_string 的名字

参阅

(C++23)
 将参数的格式化表达输出到 stdout 或文件缓冲区
(函数模板)
(C++23)
 将参数的格式化表达输出到 stdout 或文件缓冲区，输出完成后换行
(函数模板)
(C++23)
 输出各实参的格式化表示
(函数模板)