Namespaces
Variants

std:: formatter

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
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 T, class CharT = char >
struct formatter ;
(C++20 起)

std::formatter 的已启用特化定义了给定类型的格式化规则。已启用特化满足 BasicFormatter 要求，并且除非另有说明，也满足 Formatter 要求。

对于所有类型 T 和 CharT ，若未启用特化 std::formatter<T, CharT> ，则该特化为完整类型且处于禁用状态。

被禁用的特化版本不满足 Formatter 要求，且以下表达式均为 false ：

（注：根据要求，HTML标签、属性及C++专业术语均保持原文未翻译，仅对非技术性说明文字进行了本地化处理）

目录

基础标准特化

在以下列表中， 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 < class Traits, class Alloc >
struct formatter < std:: basic_string < CharT, Traits, Alloc > , CharT > ;
(7)
template < class Traits >
struct formatter < std:: basic_string_view < CharT, Traits > , CharT > ;
(8)
算术类型格式化器
template <>
struct formatter < ArithmeticT, CharT > ;
(9)
指针格式化器
template <>
struct formatter < std:: nullptr_t , CharT > ;
(10)
template <>
struct formatter < void * , CharT > ;
(11)
template <>
struct formatter < const void * , CharT > ;
(12)

其他指针及成员指针的格式化器已被禁用。

诸如 std :: formatter < wchar_t , char > 和 std :: formatter < const char * , wchar_t > 这类需要编码转换的特化版本已被禁用。

为避免将某些 char 序列格式化为 wchar_t 范围，以下特化在 C++23 中仍处于禁用状态：

禁用的 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 时解析的格式说明符的 类型 为 ? 。

所有针对字符串或字符类型的格式化器特化均为 调试启用 。

(since C++23)

标准格式规范

此章节内容不完整
原因：标准格式规范已移至单独的 页面 。本节标题为保留指向本节的链接而暂时保留，待所有相关链接处理完毕后将移除本节。

标准库类型的标准特化

<tr class="t-d
(C++20)
duration 的格式化支持
(类模板特化)
(C++20)
sys_time 的格式化支持
(类模板特化)
(C++20)
utc_time 的格式化支持
(类模板特化)
(C++20)
tai_time 的格式化支持
(类模板特化)
(C++20)
gps_time 的格式化支持
(类模板特化)
(C++20)
file_time 的格式化支持
(类模板特化)
(C++20)
local_time 的格式化支持
(类模板特化)
(C++20)
day 的格式化支持
(类模板特化)
(C++20)
month 的格式化支持
(类模板特化)
(C++20)
year 的格式化支持
(类模板特化)
(C++20)
weekday 的格式化支持
(类模板特化)
(C++20)
weekday_indexed 的格式化支持
(类模板特化)
(C++20)
weekday_last 的格式化支持
(类模板特化)
(C++20)
month_day 的格式化支持
(类模板特化)
(C++20)
month_day_last 的格式化支持
(类模板特化)
(C++20)
month_weekday 的格式化支持
(类模板特化)
(C++20)
month_weekday_last 的格式化支持
(类模板特化)

示例

运行此代码 
#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("Invalid format args for 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 范围进行格式化 禁用已添加的特化

参见

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