Namespaces
Variants

std:: format_to

From cppreference.net
C++
Text processing library
Formatting library
Standard format specification
Formatting functions
(C++20)
format_to
(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
(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 OutputIt, class ... Args >

OutputIt format_to ( OutputIt out,

std:: format_string < Args... > fmt, Args && ... args ) ;
(1) (depuis C++20)
template < class OutputIt, class ... Args >

OutputIt format_to ( OutputIt out,

std:: wformat_string < Args... > fmt, Args && ... args ) ;
(2) (depuis C++20)
template < class OutputIt, class ... Args >

OutputIt format_to ( OutputIt out, const std:: locale & loc,

std:: format_string < Args... > fmt, Args && ... args ) ;
(3) (depuis C++20)
template < class OutputIt, class ... Args >

OutputIt format_to ( OutputIt out, const std:: locale & loc,

std:: wformat_string < Args... > fmt, Args && ... args ) ;
(4) (depuis C++20)

Formate args selon la chaîne de format fmt , et écrit le résultat dans l'itérateur de sortie out . Si présent, loc est utilisé pour le formatage spécifique à la locale.

Équivalent à :

1) return std:: vformat_to ( std :: move ( out ) , fmt. str , std:: make_format_args ( args... ) ) ;
2) return std:: vformat_to ( std :: move ( out ) , fmt. str , std:: make_wformat_args ( args... ) ) ;
3) return std:: vformat_to ( std :: move ( out ) , loc, fmt. str , std:: make_format_args ( args... ) ) ;
4) return std:: vformat_to ( std :: move ( out ) , loc, fmt. str , std:: make_wformat_args ( args... ) ) ; .


Soit CharT le type char pour les surcharges (1,3) , wchar_t pour les surcharges (2,4) .

Ces surcharges participent à la résolution de surcharge seulement si OutputIt satisfait le concept std:: output_iterator < const CharT & > .

Si l'une des conditions suivantes est satisfaite, le comportement est indéfini :

Table des matières

Paramètres

out - itérateur vers le tampon de sortie
fmt -
un objet qui représente la chaîne de format. La chaîne de format se compose de
  • caractères ordinaires (sauf { et } ), qui sont copiés inchangés vers la sortie,
  • séquences d'échappement { { et } } , qui sont remplacées respectivement par { et } dans la sortie, et
  • champs de remplacement.

Chaque champ de remplacement a le format suivant :

{ arg-id (optionnel) } (1)
{ arg-id (optionnel) : format-spec } (2)
1) champ de remplacement sans spécification de format
2) champ de remplacement avec spécification de format
arg-id - spécifie l'index de l'argument dans args dont la valeur doit être utilisée pour le formatage ; s'il est omis, les arguments sont utilisés dans l'ordre.

Les arg-id dans une chaîne de format doivent tous être présents ou tous être omis. Mélanger l'indexation manuelle et automatique est une erreur.

format-spec - la spécification de format définie par la spécialisation std::formatter pour l'argument correspondant. Ne peut pas commencer par } .

(depuis C++23)
(depuis C++26)
  • Pour les autres types formatables, la spécification de format est déterminée par les spécialisations formatter définies par l'utilisateur.
args... - arguments à formater
loc - std::locale utilisée pour le formatage spécifique à la locale

Valeur de retour

Itérateur après la fin de la plage de sortie.

Exceptions

Propage toute exception levée par les opérations de formateur ou d'itérateur.

Notes

C'est une erreur si la chaîne de format n'est pas une expression constante sauf si elle est initialisée à partir du résultat de std::runtime_format (depuis C++26) . std::vformat_to n'a pas cette exigence.

Exemple

Exécuter ce code 
#include <format>
#include <iostream>
#include <iterator>
#include <string>
int main()
{
    std::string buffer;
    std::format_to
    (
        std::back_inserter(buffer), // < OutputIt
        "Hello, C++{}!\n",          // < fmt
        "20"                        // < arg
    );
    std::cout << buffer;
    buffer.clear();
    std::format_to
    (
        std::back_inserter(buffer), // < OutputIt
        "Hello, {0}::{1}!{2}",      // < fmt
        "std",                      // < arg {0}
        "format_to()",              // < arg {1}
        "\n",                       // < arg {2}
        "extra param(s)..."         // < unused
    );
    std::cout << buffer << std::flush;
    std::wstring wbuffer;
    std::format_to
    (
        std::back_inserter(wbuffer),// < OutputIt
        L"Hello, {2}::{1}!{0}",     // < fmt
        L"\n",                      // < arg {0}
        L"format_to()",             // < arg {1}
        L"std",                     // < arg {2}
        L"...is not..."             // < unused
        L"...an error!"             // < unused
    );
    std::wcout << wbuffer;
}

Sortie : 

Hello, C++20!
Hello, std::format_to()!
Hello, std::format_to()!

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 3539 C++20 out ne pouvait pas être un itérateur non copiable il peut l'être
P2216R3 C++20 lève std::format_error pour une chaîne de format invalide génère une erreur de compilation à la place
P2418R2 C++20 les objets qui ne sont ni utilisables de manière constante ni copiables
(tels que les objets de type générateur) ne sont pas formatables 		permettre le formatage de ces objets
P2508R1 C++20 il n'y a pas de nom visible par l'utilisateur pour cette fonctionnalité le nom basic_format_string est exposé

Voir aussi

(C++20)
stocke la représentation formatée des arguments dans une nouvelle chaîne
(modèle de fonction)
(C++20)
écrit la représentation formatée de ses arguments via un itérateur de sortie, sans dépasser la taille spécifiée
(modèle de fonction)