Namespaces
Variants

std:: formatter

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
Format strings
(C++20) (C++20) (C++20)
(C++26)
Formatting concepts
(C++23)
Formatter
formatter
(C++20)
(C++23)
(C++23)
(C++23)
(C++23)
(C++20) (C++20) (C++20)
(C++20) (C++20) (C++20)
(C++23)
(C++23)
Formatting arguments
(C++20)
(C++20)
(C++20) (C++20) (C++20)
(C++20) (deprecated in C++26)
(C++20) (C++20)
Format error
(C++20)
Défini dans l'en-tête <format>
template < class T, class CharT = char >
struct formatter ;
(depuis C++20)

Les spécialisations activées de std::formatter définissent les règles de formatage pour un type donné. Les spécialisations activées satisfont aux exigences BasicFormatter et, sauf indication contraire, satisfont également aux exigences Formatter .

Pour tous les types T et CharT pour lesquels aucune spécialisation std::formatter<T, CharT> n'est activée, cette spécialisation est un type complet et est désactivée.

Les spécialisations désactivées ne satisfont pas aux Formatter exigences, et les affirmations suivantes sont toutes false :

Table des matières

Spécialisations standard de base

Dans la liste suivante, CharT est soit char soit wchar_t , ArithmeticT est tout type arithmétique non qualifié cv autre que char , wchar_t , char8_t , char16_t , ou char32_t :

Formateurs de caractères
template <>
struct formatter < char , char > ;
(1)
template <>
struct formatter < char , wchar_t > ;
(2)
template <>
struct formatter < wchar_t , wchar_t > ;
(3)
Formateurs de chaînes
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)
Formateurs arithmétiques
template <>
struct formatter < ArithmeticT, CharT > ;
(9)
Formateurs de pointeurs
template <>
struct formatter < std:: nullptr_t , CharT > ;
(10)
template <>
struct formatter < void * , CharT > ;
(11)
template <>
struct formatter < const void * , CharT > ;
(12)

Les formateurs pour les autres pointeurs et les pointeurs vers les membres sont désactivés.

Les spécialisations telles que std :: formatter < wchar_t , char > et std :: formatter < const char * , wchar_t > qui nécessiteraient des conversions d'encodage sont désactivées.

Les spécialisations suivantes restent désactivées en C++23 pour éviter de formater certaines char séquences comme des plages de wchar_t :

Formateurs désactivés pour 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)

Une spécialisation de formateur à débogage activé fournit en outre une fonction membre publique non statique constexpr void set_debug_format ( ) ; qui modifie l'état de l'objet formateur afin qu'il formate les valeurs comme échappées et entre guillemets , comme si le type du spécificateur de format analysé par le dernier appel à parse était ? .

Chaque spécialisation de formateur pour les types chaîne ou caractère est à débogage activé .

(depuis C++23)

Spécification de format standard

Cette section est incomplète
Raison : La spécification du format standard est déplacée vers une page séparée . Le titre de la section est temporairement conservé pour les liens vers cette section. Cette section sera supprimée après que tous ces liens soient résolus.

Spécialisations standards pour les types de bibliothèque

(C++20)
prise en charge du formatage pour duration
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour sys_time
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour utc_time
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour tai_time
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour gps_time
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour file_time
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour local_time
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour day
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour month
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour year
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour weekday
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour weekday_indexed
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour weekday_last
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour month_day
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour month_day_last
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour month_weekday
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour month_weekday_last
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour year_month
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour year_month_day
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour year_month_day_last
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour year_month_weekday
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour year_month_weekday_last
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour hh_mm_ss
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour sys_info
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour local_info
(spécialisation de modèle de classe)
(C++20)
prise en charge du formatage pour zoned_time
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour basic_stacktrace
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour stacktrace_entry
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour thread::id
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour vector<bool>::reference
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour pair et tuple
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour les plages
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour std::stack
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour std::queue
(spécialisation de modèle de classe)
(C++23)
prise en charge du formatage pour std::priority_queue
(spécialisation de modèle de classe)
(C++26)
prise en charge du formatage pour filesystem::path
(spécialisation de modèle de classe)

Exemple

Exécuter ce code 
#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);
}

Sortie : 

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

Rapports de défauts

Les rapports de défauts modifiant le comportement suivants ont été appliqués rétroactivement aux normes C++ précédemment publiées.

DR Appliqué à Comportement publié Comportement corrigé
LWG 3944 C++23 certaines séquences char étaient formatables comme plages de wchar_t spécialisations ajoutées désactivées

Voir aussi

(C++20) (C++20) (C++20)
état de formatage, incluant tous les arguments de formatage et l'itérateur de sortie
(modèle de classe)
(C++23)
spécifie qu'un type est formatable, c'est-à-dire qu'il spécialise std::formatter et fournit les fonctions membres parse et format
(concept)
(C++23)
modèle de classe qui aide à implémenter les spécialisations de std::formatter pour les types de plages
(modèle de classe)