Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

CKTIS / C++

std::formatter: kontrakt formatowania typu

Specjalizacja std::formatter<T, charT> definiuje parsowanie specyfikacji i zapis wartości typu T.

Wersja: C++23

Składnia

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> z <format> jest punktem rozszerzenia używanym przez std::format i pokrewne funkcje dla pojedynczego argumentu. Formatter spełnia wymagania BasicFormatter/Formatter: parse(ctx) analizuje część po dwukropku i zwraca iterator pierwszego niezużytego znaku, zwykle }, a format(value, ctx) zapisuje przez ctx.out() i zwraca iterator za wynikiem.

Przykład specjalizuje std::formatter<Point> dla własnego typu. parse zwraca ctx.begin(), więc akceptuje tylko pustą specyfikację, a format deleguje zapis współrzędnych do std::format_to; wynik to p=(3, 4). Specjalizacja musi być widoczna, gdy sprawdzany jest literał formatu. Stan opcji odczytanych w parse można przechować w obiekcie formattera i wykorzystać w format.

Niepełne zużycie specyfikacji inne niż zatrzymanie na } wymaga zgłoszenia std::format_error. Sygnatura format powinna działać na wymaganej kwalifikacji wartości i na stałym formatterze, aby typ był formatowalny także jako const w C++23; zwracany iterator musi odpowiadać rzeczywistemu końcowi zapisu. Dozwolone jest specjalizowanie formattera dla typu zdefiniowanego przez program, lecz nie dowolne zmienianie specjalizacji typów standardowych. Czasy życia kontekstu i iteratorów nie wykraczają poza wywołanie.

Przykłady

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

Wynik

p=(3, 4)

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

Źródła