WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / C++

std::formatter: Formatierungsvertrag eines Typs

Eine Spezialisierung std::formatter<T, charT> definiert das Parsen der Spezifikation und die Ausgabe eines T-Werts.

Version: C++23

Syntax

template<class T, class CharT = char>
struct std::formatter;

// A usable specialization provides conceptually:
constexpr auto parse(std::basic_format_parse_context<CharT>& ctx);
template<class FormatContext>
auto format(const T& value, FormatContext& ctx) const;

std::formatter<T, charT> aus <format> ist der Anpassungspunkt, den std::format und verwandte Funktionen für ein Argument verwenden. Ein Formatter erfüllt BasicFormatter/Formatter: parse(ctx) analysiert den Teil nach dem Doppelpunkt und liefert das erste unverbrauchte Zeichen, gewöhnlich }, während format(value, ctx) über ctx.out() schreibt und den Iterator hinter der Ausgabe liefert.

Das Beispiel spezialisiert std::formatter<Point> für einen programmdefinierten Typ. parse liefert ctx.begin() und akzeptiert daher nur eine leere Spezifikation; format delegiert die Koordinaten an std::format_to. Das Ergebnis ist p=(3, 4). Die Spezialisierung muss bei der Prüfung des Formatliterals sichtbar sein. In parse gelesene Optionen dürfen im Formatter gespeichert und in format genutzt werden.

Ein nicht verarbeiteter Spezifikationsteil außer dem Halt bei } erfordert std::format_error. Die format-Signatur sollte mit der erforderlichen Wertqualifikation und einem konstanten Formatter arbeiten, damit unter C++23 auch konstante Werte formatierbar sind; ihr Rückgabeiterator muss das wirkliche Ausgabeende sein. Für programmdefinierte Typen darf spezialisiert werden, Standardspezialisierungen dürfen nicht beliebig ersetzt werden. Kontext und Iterator gelten nur während des Aufrufs.

Beispiele

#include <format>
#include <iostream>

struct Point {
    int x;
    int y;
};

template<>
struct std::formatter<Point> {
    constexpr auto parse(std::format_parse_context& ctx) {
        return ctx.begin();
    }

    auto format(const Point& point, std::format_context& ctx) const {
        return std::format_to(ctx.out(), "({}, {})", point.x, point.y);
    }
};

int main() {
    std::cout << std::format("p={}", Point{3, 4}) << '\n';
}

Ergebnis

p=(3, 4)

std::formatter → p=(3, 4)

Quellen