Namespaces
Variants

std:: to_chars

From cppreference.net
C++
Text processing library
Défini dans l'en-tête <charconv>
std :: to_chars_result

to_chars ( char * first, char * last,

/* integer-type */ value, int base = 10 ) ;
(1) (depuis C++17)
(constexpr depuis C++23)
std :: to_chars_result
to_chars ( char * , char * , bool , int = 10 ) = delete ;
(2) (depuis C++17)
std :: to_chars_result
to_chars ( char * first, char * last, /* floating-point-type */ value ) ;
(3) (depuis C++17)
std :: to_chars_result

to_chars ( char * first, char * last, /* floating-point-type */ value,

std:: chars_format fmt ) ;
(4) (depuis C++17)
std :: to_chars_result

to_chars ( char * first, char * last, /* floating-point-type */ value,

std:: chars_format fmt, int precision ) ;
(5) (depuis C++17)

Convertit value en une chaîne de caractères en remplissant successivement la plage [ first , last ) , où [ first , last ) doit être une plage valide .

1) Formateurs d'entiers : value est converti en une chaîne de chiffres dans la base donnée (sans zéros non significatifs en tête). Les chiffres dans la plage 10..35 (inclus) sont représentés par les caractères minuscules a..z . Si value est inférieur à zéro, la représentation commence par un signe moins. La bibliothèque fournit des surcharges pour tous les types entiers signés et non signés sans qualificatif cv, ainsi que pour le type char comme type du paramètre value .
2) La surcharge pour bool est supprimée. std::to_chars rejette l'argument de type bool car le résultat serait "0" / "1" et non "false" / "true" si elle était autorisée.
3) value est convertie en chaîne selon le style de std::printf dans la locale par défaut ("C"). Le spécificateur de conversion est f ou e (en privilégiant f en cas d'égalité), choisi selon l'exigence d'une représentation la plus courte : la représentation sous forme de chaîne consiste en le plus petit nombre de caractères tel qu'il y ait au moins un chiffre avant le point décimal (s'il est présent) et que l'analyse de la représentation à l'aide de la fonction std::from_chars correspondante restitue exactement la valeur. S'il existe plusieurs représentations de ce type, celle avec la plus petite différence par rapport à value est choisie, en résolvant les égalités restantes par arrondi selon std::round_to_nearest . La bibliothèque fournit des surcharges pour tous les types standard (jusqu'à C++23) à virgule flottante non qualifiés cv comme type du paramètre value .
4) Identique à (3) , mais la conversion spécifiée pour le printf virtuel est f si fmt vaut std::chars_format::fixed , e si fmt vaut std::chars_format::scientific , a (mais sans le préfixe "0x" dans le résultat) si fmt vaut std::chars_format::hex , et g si fmt vaut chars_format::general . La bibliothèque fournit des surcharges pour tous les types standard (jusqu'à C++23) à virgule flottante non qualifiés cv comme type du paramètre value .
5) Identique à (4) , sauf que la précision est spécifiée par le paramètre precision plutôt que par l'exigence de représentation la plus courte. La bibliothèque fournit des surcharges pour tous les types standard (jusqu'à C++23) à virgule flottante non qualifiés cv comme type du paramètre value .

Table des matières

Paramètres

first, last - plage de caractères à écrire
value - la valeur à convertir en sa représentation sous forme de chaîne
base - base entière à utiliser : une valeur comprise entre 2 et 36 (inclus).
fmt - formatage des nombres à virgule flottante à utiliser, un masque de bits de type std::chars_format
precision - précision des nombres à virgule flottante à utiliser

Valeur de retour

En cas de succès, retourne une valeur de type std::to_chars_result telle que ec soit égal à une valeur initialisée par défaut de std::errc et que ptr soit le pointeur situé juste après le dernier caractère écrit. Notez que la chaîne n'est pas terminée par un caractère NUL.

En cas d'erreur, retourne une valeur de type std::to_chars_result contenant std::errc::value_too_large dans ec , une copie de la valeur last dans ptr , et laisse le contenu de l'intervalle [ first , last ) dans un état non spécifié.

Exceptions

Ne lance rien.

Notes

Contrairement aux autres fonctions de formatage dans les bibliothèques C++ et C, std::to_chars est indépendant des paramètres régionaux, n'effectue pas d'allocation et ne lève pas d'exceptions. Seul un petit sous-ensemble des politiques de formatage utilisées par d'autres bibliothèques (telles que std::sprintf ) est fourni. Cela vise à permettre l'implémentation la plus rapide possible, utile dans des contextes courants à haut débit tels que l'échange basé sur le texte ( JSON ou XML ).

La garantie que std::from_chars peut récupérer exactement chaque valeur en virgule flottante formatée par std::to_chars est uniquement fournie si les deux fonctions proviennent de la même implémentation.

Pour formater une valeur bool en tant que "0" / "1" en utilisant std::to_chars , la valeur doit être convertie en un autre type entier.

Macro de test de fonctionnalité Valeur Std Fonctionnalité
__cpp_lib_to_chars 201611L (C++17) Conversions élémentaires de chaînes ( std::to_chars , std::from_chars )
202306L (C++26) Test de réussite ou d'échec des fonctions <charconv>
__cpp_lib_constexpr_charconv 202207L (C++23) Ajout des modificateurs constexpr aux surcharges de std::to_chars et std::from_chars ( 1 ) pour les types entiers

Exemple

Exécuter ce code 
#include <charconv>
#include <iomanip>
#include <iostream>
#include <string_view>
#include <system_error>
void show_to_chars(auto... format_args)
{
    const size_t buf_size = 10;
    char buf[buf_size]{};
    std::to_chars_result result = std::to_chars(buf, buf + buf_size, format_args...);
    if (result.ec != std::errc())
        std::cout << std::make_error_code(result.ec).message() << '\n';
    else
    {
        std::string_view str(buf, result.ptr - buf);
        std::cout << std::quoted(str) << '\n';
    }
}
int main()
{
    show_to_chars(42);
    show_to_chars(+3.14159F);
    show_to_chars(-3.14159, std::chars_format::fixed);
    show_to_chars(-3.14159, std::chars_format::scientific, 3);
    show_to_chars(3.1415926535, std::chars_format::fixed, 10);
}

Sortie possible : 

"42"
"3.14159"
"-3.14159"
"-3.142e+00"
Value too large for defined data type

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 2955 C++17 cette fonction était dans <utility> et utilisait std::error_code déplacée vers <charconv> et utilise std::errc
LWG 3266 C++17 bool l'argument était accepté et promu en int rejeté par une surcharge supprimée
LWG 3373 C++17 std::to_chars_result pouvait avoir des membres supplémentaires les membres supplémentaires sont interdits

Voir aussi

(C++17)
le type de retour de std::to_chars
(classe)
(C++17)
convertit une séquence de caractères en une valeur entière ou à virgule flottante
(fonction)
(C++11)
convertit une valeur entière ou à virgule flottante en string
(fonction)
(C++11)
imprime une sortie formatée vers stdout , un flux de fichier ou un tampon
(fonction)
insère des données formatées
(fonction membre publique de std::basic_ostream<CharT,Traits> )