std::formatter

 

C++

Compiler-Unterstützung

Freestanding und gehostet

Sprache

Standardbibliothek

Header der Standardbibliothek

Benannte Anforderungen

Feature-Test-Makros (C++20)

Bibliothek für Sprachunterstützung

Konzepte-Bibliothek (C++20)

Diagnostik-Bibliothek

Speicherverwaltungsbibliothek

Metaprogrammierungsbibliothek (C++11)

Allgemeine Dienstprogramme-Bibliothek

Container-Bibliothek

Iterator-Bibliothek

Ranges-Bibliothek (C++20)

Algorithmen-Bibliothek

Bibliothek für Zeichenketten

Textverarbeitungsbibliothek

Numerik-Bibliothek

Datums- und Zeitbibliothek

Ein-/Ausgabe-Bibliothek

Dateisystembibliothek (C++17)

Unterstützung für nebenläufige Programmierung (C++11)

Ausführungssteuerungsbibliothek (C++26)

Technische Spezifikationen

Symbolverzeichnis

Externe Bibliotheken

 

Textverarbeitungsbibliothek

Lokalisierungsbibliothek

Reguläre Ausdrücke-Bibliothek (C++11)

Formatierungsbibliothek (C++20)

Dienstprogramme für Null-terminierte Sequenzen

Byte-Zeichenketten

Multibyte-Zeichenketten

Wide-Zeichenketten

Primitive numerische Konvertierungen

to_chars (C++17) to_chars_result (C++17) from_chars (C++17) from_chars_result (C++17) chars_format (C++17)

Textkodierungserkennung

text_encoding (C++26)

 

Formatierungsbibliothek

Standardformat-Spezifikation

Formatierungsfunktionen

format (C++20)

format_to (C++20)

format_to_n (C++20)

formatted_size (C++20)

vformat (C++20)

vformat_to (C++20)

Format-Strings

basic_format_stringformat_stringwformat_string (C++20)(C++20)(C++20)

runtime_format (C++26)

Formatierungs-Konzepte

formattable (C++23)

Formatter

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)

Formatierungs-Argumente

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) (veraltet in C++26)

make_format_argsmake_wformat_args (C++20)(C++20)

Format-Fehler

format_error (C++20)

 

Definiert in Header <format>
template< class T, class CharT = char > struct formatter;		(seit C++20)

Die aktivierten Spezialisierungen von std::formatter definieren Formatierungsregeln für einen gegebenen Typ. Aktivierte Spezialisierungen erfüllen die Anforderungen von BasicFormatter und, sofern nicht anders angegeben, auch die Anforderungen von Formatter.

Für alle Typen T und CharT, für die keine Spezialisierung std::formatter<T, CharT> aktiviert ist, ist diese Spezialisierung ein vollständiger Typ und ist deaktiviert.

Deaktivierte Spezialisierungen erfüllen nicht die Anforderungen von Formatter, und die folgenden sind alle false

• std::is_default_constructible_v
• std::is_copy_constructible_v
• std::is_move_constructible_v
• std::is_copy_assignable_v
• std::is_move_assignable_v.

Grundlegende Standard-Spezialisierungen

In der folgenden Liste ist CharT entweder char oder wchar_t, ArithmeticT ist jeder cv-unqualifizierte arithmetische Typ außer char, wchar_t, char8_t, char16_t oder char32_t

Zeichen-Formatter
template<> struct formatter<char, char>;	(1)
template<> struct formatter<char, wchar_t>;	(2)
template<> struct formatter<wchar_t, wchar_t>;	(3)
String-Formatter
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)
Arithmetische Formatter
template<> struct formatter<ArithmeticT, CharT>;	(9)
Zeiger-Formatter
template<> struct formatter<std::nullptr_t, CharT>;	(10)
template<> struct formatter<void*, CharT>;	(11)
template<> struct formatter<const void*, CharT>;	(12)

Formatter für andere Zeiger und Zeiger auf Member sind deaktiviert.

Spezialisierungen wie std::formatter<wchar_t, char> und std::formatter<const char*, wchar_t>, die Kodierungskonvertierungen erfordern würden, sind deaktiviert.

Die folgenden Spezialisierungen sind in C++23 weiterhin deaktiviert, um die Formatierung einiger char-Sequenzen als Bereiche von wchar_t zu vermeiden. Deaktivierte Formatter für 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) Eine *debug-aktivierte* Formatter-Spezialisierung stellt zusätzlich eine öffentliche nicht-statische Member-Funktion constexpr void set_debug_format(); bereit, die den Zustand des Formatter-Objekts so modifiziert, dass es Werte als escaped und zitiert formatiert, als wäre der *Typ* des durch den letzten Aufruf von parse analysierten Format-Spezifizierers ?. Jede Formatter-Spezialisierung für Zeichen- oder String-Typen ist *debug-aktiviert*.

(seit C++23)

Standard-Spezialisierungen für Bibliothekstypen

std::formatter<std::chrono::duration> (C++20)	Formatierungsunterstützung für duration (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::sys_time> (C++20)	Formatierungsunterstützung für sys_time (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::utc_time> (C++20)	Formatierungsunterstützung für utc_time (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::tai_time> (C++20)	Formatierungsunterstützung für tai_time (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::gps_time> (C++20)	Formatierungsunterstützung für gps_time (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::file_time> (C++20)	Formatierungsunterstützung für file_time (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::local_time> (C++20)	Formatierungsunterstützung für local_time (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::day> (C++20)	Formatierungsunterstützung für day (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::month> (C++20)	Formatierungsunterstützung für month (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::year> (C++20)	Formatierungsunterstützung für year (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::weekday> (C++20)	Formatierungsunterstützung für weekday (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::weekday_indexed> (C++20)	Formatierungsunterstützung für weekday_indexed (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::weekday_last> (C++20)	Formatierungsunterstützung für weekday_last (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::month_day> (C++20)	Formatierungsunterstützung für month_day (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::month_day_last> (C++20)	Formatierungsunterstützung für month_day_last (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::month_weekday> (C++20)	Formatierungsunterstützung für month_weekday (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::month_weekday_last> (C++20)	Formatierungsunterstützung für month_weekday_last (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::year_month> (C++20)	Formatierungsunterstützung für year_month (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::year_month_day> (C++20)	Formatierungsunterstützung für year_month_day (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::year_month_day_last> (C++20)	Formatierungsunterstützung für year_month_day_last (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::year_month_weekday> (C++20)	Formatierungsunterstützung für year_month_weekday (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::year_month_weekday_last> (C++20)	Formatierungsunterstützung für year_month_weekday_last (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::hh_mm_ss> (C++20)	Formatierungsunterstützung für hh_mm_ss (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::sys_info> (C++20)	Formatierungsunterstützung für sys_info (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::local_info> (C++20)	Formatierungsunterstützung für local_info (Klassentemplate-Spezialisierung)
std::formatter<std::chrono::zoned_time> (C++20)	Formatierungsunterstützung für zoned_time (Klassentemplate-Spezialisierung)
std::formatter<std::basic_stacktrace> (C++23)	Formatierungsunterstützung für basic_stacktrace (Klassenvorlagenspezialisierung)
std::formatter<std::stacktrace_entry> (C++23)	Formatierungsunterstützung für stacktrace_entry (Klassenvorlagenspezialisierung)
std::formatter<std::thread::id> (C++23)	Formatierungsunterstützung für thread::id (Klassenvorlagenspezialisierung)
std::formatter<std::vector<bool>::reference> (C++23)	Formatierungsunterstützung für vector<bool>::reference (Klassenvorlagenspezialisierung)
std::formatter<pair-or-tuple> (C++23)	Formatierungsunterstützung für pair und tuple (Klassenvorlagenspezialisierung)
std::formatter<range> (C++23)	Formatierungsunterstützung für Bereiche (Klassenvorlagenspezialisierung)
std::formatter<std::stack> (C++23)	Formatierungsunterstützung für std::stack (Klassenvorlagenspezialisierung)
std::formatter<std::queue> (C++23)	Formatierungsunterstützung für std::queue (Klassenvorlagenspezialisierung)
std::formatter<std::priority_queue> (C++23)	Formatierungsunterstützung für std::priority_queue (Klassenvorlagenspezialisierung)
std::formatter<std::filesystem::path> (C++26)	Formatierungsunterstützung für filesystem::path (Klassenvorlagenspezialisierung)

Beispiel

Führen Sie diesen Code aus

#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);
}

Ausgabe

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".

Fehlerberichte

Die folgenden Verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR	angewendet auf	Verhalten wie veröffentlicht	Korrigiertes Verhalten
LWG 3944	C++23	einige char-Sequenzen konnten als Bereiche von wchar_t formatiert werden	Spezialisierungen deaktiviert

Siehe auch

basic_format_contextformat_contextwformat_context (C++20)(C++20)(C++20)	Formatierungsstatus, einschließlich aller Formatierungsargumente und des Output-Iterators (Klassentemplate)
formattable (C++23)	gibt an, dass ein Typ formatierbar ist, d.h., er spezialisiert std::formatter und stellt die Member-Funktionen parse und format bereit (Konzept)
range_formatter (C++23)	Klassenvorlage, die bei der Implementierung von std::formatter-Spezialisierungen für Bereichstypen hilft (Klassentemplate)