Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C++

std::formatter: contrato de formatação de um tipo

Uma especialização std::formatter<T, charT> define a análise da especificação e a escrita de um valor T.

Versão: C++23

Sintaxe

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> de <format> é o ponto de personalização usado por std::format e funções relacionadas para um argumento. Um formatter satisfaz BasicFormatter/Formatter: parse(ctx) analisa a parte após os dois pontos e devolve o primeiro carácter não consumido, normalmente }, enquanto format(value, ctx) escreve por ctx.out() e devolve o iterador após a saída.

O exemplo especializa std::formatter<Point> para um tipo do programa. parse devolve ctx.begin(), aceitando apenas uma especificação vazia, e format delega as coordenadas em std::format_to; o resultado é p=(3, 4). A especialização tem de estar visível quando o literal é verificado. Opções lidas em parse podem ser guardadas no formatter e usadas em format.

Deixar uma parte por analisar, além de parar em }, exige std::format_error. A assinatura de format deve aceitar a qualificação exigida do valor e um formatter const para que valores const sejam formatáveis em C++23; o iterador devolvido tem de ser o fim real da saída. É permitido especializar para um tipo definido pelo programa, não substituir arbitrariamente especializações de tipos padrão. O contexto e os iteradores não sobrevivem à chamada.

Exemplos

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

Resultado

p=(3, 4)

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

Fontes