std::formatter

Определён в заголовочном файле `<format>`
template< class T, class CharT = char > struct formatter;		(начиная с C++20)

Включённые специализации std::formatter задают правила форматирования для заданного типа. Включённые специализации соответствуют требованиям BasicFormatter и, если не указано иное, также требованиям Formatter.

Для всех типов T и CharT, для которых специализация std::formatter<T, CharT> не включена, эта специализация является полным типом и отключена.

Отключённые специализации не соответствуют требованиям Formatter, и для них выполняются все следующие условия false:

Базовые стандартные специализации

В следующем списке CharT — это либо char, либо wchar_t, а ArithmeticT — любой арифметический тип без квалификаторов cv, кроме char, wchar_t, char8_t, char16_t и char32_t:

Форматтеры символов
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<constchar*,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, был ?.

Каждая специализация форматтера для строкового или символьного типа поддерживает отладку.

(начиная с 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-or-tuple> (C++23)	поддержка форматирования для `pair` и `tuple` (специализация шаблона класса)
std::formatter<range> (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("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++.

DR	Применён к	Поведение согласно опубликованной версии	Корректное поведение
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` для типов-диапазонов (шаблон класса)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/cpp/utility/format/formatter