std::formatter

在标头 `<format>` 定义
template< class T, class CharT = char > struct formatter;		(C++20 起)

std::formatter 的被启用特化对给定类型定义格式化规则。被启用特化满足基本格式化器 (BasicFormatter) 要求，并且除非另有规定，否则也满足格式化器 (Formatter) 要求。

对每组未对其启用特化 std::formatter<T, CharT> 的类型 T 与 CharT，该特化是完整类型且被禁用。

被禁用特化不满足格式化器 (Formatter) 要求，且下列值都是 false：

基本的标准特化

以下列表中，CharT 是 char 或 wchar_t，ArithmeticT 是除了 char、wchar_t、char8_t、char16_t 或 char32_t 之外的任何无 cv 限定的算术类型。

字符格式化器
template<> struct formatter<char, char>;	(1)
template<> struct formatter<char, wchar_t>;	(2)
template<> struct formatter<wchar_t, wchar_t>;	(3)
字符串格式化器
template<> struct formatter<CharT*, CharT>;	(4)
template<> struct formatter<const CharT*, CharT>;	(5)
template< std::size_t N > struct formatter<CharT[N], CharT>;	(6)
template< std::size_t N > struct formatter<const CharT[N], CharT>;	(7)	(C++23 前)
template< class Traits, class Alloc > struct formatter<std::basic_string<CharT, Traits, Alloc>, CharT>;	(8)
template< class Traits > struct formatter<std::basic_string_view<CharT, Traits>, CharT>;	(9)
算术格式化器
template<> struct formatter<ArithmeticT, CharT>;	(10)
指针格式化器
template<> struct formatter<std::nullptr_t, CharT>;	(11)
template<> struct formatter<void*, CharT>;	(12)
template<> struct formatter<const void*, CharT>;	(13)

针对其他指针和成员指针的格式化器被禁用。

如 std::formatter<wchar_t, char> 和 std::formatter<const char*, wchar_t> 这些会要求编码转换的特化被禁用。

C++23 中下列特化仍然被禁用，以避免将某些 char 序列作为 wchar_t 的范围格式化：

对 wchar_t 禁用的特化
template<> struct formatter<char*, wchar_t>;	(1)
template<> struct formatter<const char*, wchar_t>;	(2)
template< std::size_t N > struct formatter<char[N], wchar_t>;	(3)
template< class Traits, class Allocator > struct formatter<std::basic_string<char, Traits, Allocator>, wchar_t>;	(4)
template< class Traits > struct formatter<std::basic_string_view<char, Traits>, wchar_t>;	(5)

启用调试的格式化器特化都会另外提供一个公开的非静态成员函数 constexpr void set_debug_format();，它会修改格式化器对象的状态，使该对象可以在格式化时进行转义和使用引号包围，如同上次调用 parse 的格式化说明符中类型是 ?。

每个针对字符串或字符类型的 std::formatter 特化都是启用调试的。

(C++23 起)

标准格式说明

库类型的标准特化

std::formatter<std::chrono::duration> (C++20)	`duration` 的格式化支持 (类模板特化)
std::formatter<std::chrono::sys_time> (C++20)	`sys_time` 的格式化支持 (类模板特化)
std::formatter<std::chrono::utc_time> (C++20)	`utc_time` 的格式化支持 (类模板特化)
std::formatter<std::chrono::tai_time> (C++20)	`tai_time` 的格式化支持 (类模板特化)
std::formatter<std::chrono::gps_time> (C++20)	`gps_time` 的格式化支持 (类模板特化)
std::formatter<std::chrono::file_time> (C++20)	`file_time` 的格式化支持 (类模板特化)
std::formatter<std::chrono::local_time> (C++20)	`local_time` 的格式化支持 (类模板特化)
std::formatter<std::chrono::day> (C++20)	`day` 的格式化支持 (类模板特化)
std::formatter<std::chrono::month> (C++20)	`month` 的格式化支持 (类模板特化)
std::formatter<std::chrono::year> (C++20)	`year` 的格式化支持 (类模板特化)
std::formatter<std::chrono::weekday> (C++20)	`weekday` 的格式化支持 (类模板特化)
std::formatter<std::chrono::weekday_indexed> (C++20)	`weekday_indexed` 的格式化支持 (类模板特化)
std::formatter<std::chrono::weekday_last> (C++20)	`weekday_last` 的格式化支持 (类模板特化)
std::formatter<std::chrono::month_day> (C++20)	`month_day` 的格式化支持 (类模板特化)
std::formatter<std::chrono::month_day_last> (C++20)	`month_day_last` 的格式化支持 (类模板特化)
std::formatter<std::chrono::month_weekday> (C++20)	`month_weekday` 的格式化支持 (类模板特化)
std::formatter<std::chrono::month_weekday_last> (C++20)	`month_weekday_last` 的格式化支持 (类模板特化)
std::formatter<std::chrono::year_month> (C++20)	`year_month` 的格式化支持 (类模板特化)
std::formatter<std::chrono::year_month_day> (C++20)	`year_month_day` 的格式化支持 (类模板特化)
std::formatter<std::chrono::year_month_day_last> (C++20)	`year_month_day_last` 的格式化支持 (类模板特化)
std::formatter<std::chrono::year_month_weekday> (C++20)	`year_month_weekday` 的格式化支持 (类模板特化)
std::formatter<std::chrono::year_month_weekday_last> (C++20)	`year_month_weekday_last` 的格式化支持 (类模板特化)
std::formatter<std::chrono::hh_mm_ss> (C++20)	`hh_mm_ss` 的格式化支持 (类模板特化)
std::formatter<std::chrono::sys_info> (C++20)	`sys_info` 的格式化支持 (类模板特化)
std::formatter<std::chrono::local_info> (C++20)	`local_info` 的格式化支持 (类模板特化)
std::formatter<std::chrono::zoned_time> (C++20)	`zoned_time` 的格式化支持 (类模板特化)
std::formatter<std::basic_stacktrace> (C++23)	`basic_stacktrace` 的格式化支持 (类模板特化)
std::formatter<std::stacktrace_entry> (C++23)	`stacktrace_entry` 的格式化支持 (类模板特化)
std::formatter<std::thread::id> (C++23)	`thread::id` 的格式化支持 (类模板特化)
std::formatter<std::vector<bool>::reference> (C++23)	`vector<bool>::reference` 的格式化支持 (类模板特化)
std::formatter<pair 或 tuple> (C++23)	`pair` 和 `tuple` 的格式化支持 (类模板特化)
std::formatter<范围> (C++23)	范围的格式化支持 (类模板特化)
std::formatter<std::stack> (C++23)	`std::stack` 的格式化支持 (类模板特化)
std::formatter<std::queue> (C++23)	`std::queue` 的格式化支持 (类模板特化)
std::formatter<std::priority_queue> (C++23)	`std::priority_queue` 的格式化支持 (类模板特化)
std::formatter<std::filesystem::path> (C++26)	`filesystem::path` 的格式化支持 (类模板特化)

示例

运行此代码

#include <algorithm>
#include <format>
#include <iomanip>
#include <iostream>
#include <sstream>
#include <string_view>
 
struct QuotableString : std::string_view
{};
 
template<>
struct std::formatter<QuotableString, char>
{
    bool quoted = false;
 
    template<class ParseContext>
    constexpr ParseContext::iterator parse(ParseContext& ctx)
    {
        auto it = ctx.begin();
        if (it == ctx.end())
            return it;
 
        if (*it == '#')
        {
            quoted = true;
            ++it;
        }
        if (it != ctx.end() && *it != '}')
            throw std::format_error("无效的 QuotableString 格式参数。");
 
        return it;
    }
 
    template<class FmtContext>
    FmtContext::iterator format(QuotableString s, FmtContext& ctx) const
    {
        std::ostringstream out;
        if (quoted)
            out << std::quoted(s);
        else
            out << s;
 
        return std::ranges::copy(std::move(out).str(), ctx.out()).out;
    }
};
 
int main()
{
    QuotableString a("be"), a2(R"( " be " )");
    QuotableString b("a question");
    std::cout << std::format("To {0} or not to {0}, that is {1}.\n", a, b);
    std::cout << std::format("To {0:} or not to {0:}, that is {1:}.\n", a, b);
    std::cout << std::format("To {0:#} or not to {0:#}, that is {1:#}.\n", a2, b);
}

输出：

To be or not to be, that is a question.
To be or not to be, that is a question.
To " \" be \" " or not to " \" be \" ", that is "a question".

缺陷报告

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

缺陷报告	应用于	出版时的行为	正确行为
LWG 3944	C++23	某些 char 序列能作为 wchar_t 的范围格式化	添加了禁用的特化

参阅

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	格式化状态，包括所有格式化参数和输出迭代器 (类模板)
formattable (C++23)	指示一个类型可格式化，即它特化了 std::formatter 并且提供了成员函数 `parse` 和 `format` (概念)
range_formatter (C++23)	用于帮助实现 std::formatter 对范围类型的特化的类模板 (类模板)

编译器支持
自立实现与有宿主实现
语言
标准库
标准库标头
具名要求
功能特性测试宏 (C++20)
语言支持库
概念库 (C++20)
元编程库 (C++11)
诊断库
通用工具库
字符串库
容器库
迭代器库
范围库 (C++20)
算法库
数值库
本地化库
输入/输出库
文件系统库 (C++17)
正则表达式库 (C++11)
并发支持库 (C++11)
技术规范
符号索引
外部库

标准格式说明
格式化函数
format (C++20)
format_to (C++20)
format_to_n (C++20)
formatted_size (C++20)
vformat (C++20)
vformat_to (C++20)
格式字符串
basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)
runtime_format (C++26)
格式化概念
formattable (C++23)
格式化器
formatter (C++20)
formatter<pair-or-tuple> (C++23)
formatter<range> (C++23)
range_formatter (C++23)
enable_nonlocking_formatter_optimization (C++23)
basic_format_parse_contextformat_parse_contextwformat_parse_context (C++20)(C++20)(C++20)
basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)
range_format (C++23)
format_kind (C++23)
格式化参数
basic_format_arg (C++20)
basic_format_arg::handle (C++20)
basic_format_argsformat_argswformat_args (C++20)(C++20)(C++20)
visit_format_arg (C++20) (C++26 中弃用)
make_format_argsmake_wformat_args (C++20)(C++20)
格式错误
format_error (C++20)

std::formatter

基本的标准特化

标准格式说明

库类型的标准特化

示例

缺陷报告

参阅

导航