Namespaces
Variants

std:: format_to_n, std:: format_to_n_result

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,
const std:: locale & loc,

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

std :: format_to_n_result < OutputIt >
format_to_n ( OutputIt out, std:: iter_difference_t < OutputIt > n,
const std:: locale & loc,

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

struct format_to_n_result {
OutputIt out ;
std:: iter_difference_t < OutputIt > size ;

} ;
(5) (depuis C++20)

Formate args selon la chaîne de format fmt , et écrit le résultat dans l'itérateur de sortie out . Au maximum n caractères sont écrits. Si présent, loc est utilisé pour le formatage spécifique aux paramètres régionaux.

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

Le comportement n'est pas défini si OutputIt ne modélise pas (ne satisfait pas aux exigences sémantiques du) concept std:: output_iterator < const CharT & > , ou si std:: formatter < std:: remove_cvref_t < Ti > , CharT > ne satisfait pas aux exigences du BasicFormatter pour tout Ti dans Args .

5) std::format_to_n_result n'a pas de classes de base, ni de membres autres que out , size et les fonctions membres spéciales déclarées implicitement.

Table des matières

Paramètres

out - itérateur vers le tampon de sortie
n - nombre maximum de caractères à écrire dans le tampon
fmt -
un objet qui représente la chaîne de format. La chaîne de format est constituée 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 s 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é pour le formatage spécifique à la locale

Valeur de retour

Un format_to_n_result tel que le membre out soit un itérateur situé après la fin de la plage de sortie, et le membre size soit la taille totale (non tronquée) de la sortie.

Exceptions

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

Notes

L'implémentation de libstdc++ avant GCC-13.3 comportait un bogue dans le rapport de la valeur correcte de format_to_n_result :: out .

Exemple

Sur Godbolt's Compiler Explorer : clang (trunk) + libc++ , GCC (trunk) + libstdc++ .

Exécuter ce code 
#include <format>
#include <initializer_list>
#include <iomanip>
#include <iostream>
#include <string_view>
int main()
{
    char buffer[64];
    for (std::size_t max_chars_to_write : {std::size(buffer) - 1, 23uz, 21uz})
    {
        const std::format_to_n_result result =
            std::format_to_n(
                buffer, max_chars_to_write,
                "Hubble's H{2} {3} {0}{4}{1} km/sec/Mpc.", // 24 bytes w/o formatters
                71,       // {0}, occupies 2 bytes
                8,        // {1}, occupies 1 byte
                "\u2080", // {2}, occupies 3 bytes, '₀' (SUBSCRIPT ZERO)
                "\u2245", // {3}, occupies 3 bytes, '≅' (APPROXIMATELY EQUAL TO)
                "\u00B1"  // {4}, occupies 2 bytes, '±' (PLUS-MINUS SIGN)
                ); // 24 + 2 + 1 + 3 + 3 + 2 == 35, no trailing '\0'
        *result.out = '\0'; // adds terminator to buffer
        const std::string_view str(buffer, result.out);
        std::cout << "Buffer until '\\0': " << std::quoted(str) << '\n'
                  << "Max chars to write: " << max_chars_to_write << '\n'
                  << "result.out offset: " << result.out - buffer << '\n'
                  << "Untruncated output size: " << result.size << "\n\n";
    }
}

Sortie : 

Buffer until '\0': "Hubble's H₀ ≅ 71±8 km/sec/Mpc."
Max chars to write: 63
result.out offset: 35
Untruncated output size: 35
Buffer until '\0': "Hubble's H₀ ≅ 71±8"
Max chars to write: 23
result.out offset: 23
Untruncated output size: 35
Buffer until '\0': "Hubble's H₀ ≅ 71�"
Max chars to write: 21
result.out offset: 21
Untruncated output size: 35

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 tel que publié Comportement corrigé
P2216R3 C++20 lève std::format_error pour une chaîne de format invalide une chaîne de format invalide génère une erreur à la compilation
P2418R2 C++20 les objets qui ne sont ni const-utilisables 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'existe 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
(modèle de fonction)
(C++20)
détermine le nombre de caractères nécessaires pour stocker la représentation formatée de ses arguments
(modèle de fonction)