fonctions`<charconv>`

Article
10/12/2023

L’en-tête <charconv> inclut les fonctions non membres suivantes :

Fonctions non membres	Description
to_chars	Convertissez une valeur entière ou à virgule flottante en une séquence de `char`.
from_chars	Convertissez une séquence d’un `char` entier ou d’une valeur à virgule flottante.

Ces fonctions de conversion sont paramétrées pour les performances et prennent également en charge le comportement aller-retour le plus court. Le comportement aller-retour le plus court signifie qu’un nombre est converti en caractères, seule une précision suffisante est écrite pour permettre de récupérer le nombre d’origine lors de la conversion de ces caractères en virgule flottante.

Lors de la conversion de caractères en nombre, la valeur numérique n’a pas besoin d’être terminée par null. De même, lors de la conversion d’un nombre en caractères, le résultat n’est pas terminé par null.
Les fonctions de conversion n’allouent pas de mémoire. Vous êtes propriétaire de la mémoire tampon dans tous les cas.
Les fonctions de conversion ne lèvent pas. Un résultat est retourné à partir duquel vous pouvez déterminer si la conversion a réussi.
Les fonctions de conversion ne respectent pas le mode arrondi du runtime.
Les fonctions de conversion ne sont pas conscientes des paramètres régionaux. Ils impriment et analysent toujours les décimales comme '.', et jamais comme « , pour les paramètres régionaux qui utilisent des virgules.

`to_chars`

Convertissez une valeur entière ou à virgule flottante en une séquence de char.

Convertit en chaîne de value caractères en remplissant la plage [first, last), où [first, last) doit être une plage valide. Retourne une structure to_chars_result. Si la conversion réussit, comme indiqué par to_char_result.ec, le membre ptr est le pointeur un-past-the-end des caractères écrits. Sinon, to_char_result.ec a la valeur errc::value_too_large, to_char_result.ptr a la valeur last, et le contenu de la plage [first, last) n’est pas spécifié.

La seule façon d’échouer to_chars est si vous fournissez une mémoire tampon insuffisante pour contenir le résultat.

// integer to chars

to_chars_result to_chars(char* first, char* last, char value, int base = 10);
to_chars_result to_chars(char* first, char* last, signed char value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned char value, int base = 10);
to_chars_result to_chars(char* first, char* last, short value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned short value, int base = 10);
to_chars_result to_chars(char* first, char* last, int value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned int value, int base = 10);
to_chars_result to_chars(char* first, char* last, long value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned long value, int base = 10);
to_chars_result to_chars(char* first, char* last, long long value, int base = 10);
to_chars_result to_chars(char* first, char* last, unsigned long long value, int base = 10);
to_chars_result to_chars(char* first, char* last, bool value, int base = 10) = delete;

// floating-point to chars

to_chars_result to_chars(char* first, char* last, float value);
to_chars_result to_chars(char* first, char* last, double value);
to_chars_result to_chars(char* first, char* last, long double value);
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt);
to_chars_result to_chars(char* first, char* last, float value, chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, double value, chars_format fmt, int precision);
to_chars_result to_chars(char* first, char* last, long double value, chars_format fmt, int precision);

Paramètres

first
Pointe vers le début de la mémoire tampon à remplir.

last
Pointe un caractère au-delà de la fin de la mémoire tampon à remplir.

valeur
La valeur à convertir. Si value elle est négative, la représentation commence par -.

base
Pour les conversions d’entiers, la base à utiliser lors de la conversion en value caractères. Doit être compris entre 2 et 36, inclus. Il n’y aura pas de zéros non significatifs. Les chiffres de la plage 10..35 (inclus) sont représentés sous forme de caractères minuscules a.. z

Fmt
Pour les conversions à virgule flottante, masque de bits spécifiant le format de conversion à utiliser comme scientifique, fixe ou hexadécimal. Pour plus d’informations, consultez chars_format .

precision
Pour les conversions à virgule flottante, nombre de chiffres de précision pour la valeur convertie.

Valeur retournée

Un to_chars_result contenant le résultat de la conversion.

Notes

Les fonctions prenant un paramètre chars_format déterminent le spécificateur de conversion comme s’ils utilisaient printf() comme suit : le spécificateur de conversion est si c’est fmt 'f' , si fmt c’est chars_format::scientificchars_format::fixed, 'a' 'e' (sans le début 0x dans le résultat) si fmt c’est chars_format::hex, et 'g' si fmt c’est chars_format::general. La spécification de la notation fixe la plus courte peut encore entraîner une sortie longue, car il peut s’agir de la représentation la plus courte possible lorsque la valeur est très grande ou très petite.

Le tableau suivant décrit le comportement de conversion en fonction de différentes combinaisons et fmt precision paramètres. Le terme « comportement aller-retour le plus court » fait référence à l’écriture du plus petit nombre de chiffres nécessaires pour que l’analyse de cette représentation à l’aide de la fonction correspondante from_chars récupère exactement la valeur.

`fmt` et `precision` combinaison	Sortie
Aucun	Quelle que soit la notation fixe ou scientifique est plus courte, préférez fixe comme un brise-cravate. Ce comportement ne peut pas être simulé par une surcharge qui accepte le `fmt` paramètre.
`fmt`	Comportement d’aller-retour le plus court pour le format spécifié, tel que le format scientifique le plus court.
`fmt` et `precision`	Utilise la précision donnée, en suivant `printf()` le style, sans comportement aller-retour le plus court.

Exemple

#include <charconv>
#include <stdio.h>
#include <system_error>

template <typename T> void TestToChars(const T t)
{
    static_assert(std::is_floating_point_v<T>);
    constexpr bool IsFloat = std::is_same_v<T, float>;

    char buf[100]; // 100 is large enough for double and long double values because the longest possible outputs are "-1.23456735e-36" and "-1.2345678901234567e-100".
    constexpr size_t size = IsFloat ? 15 : 24;
    const std::to_chars_result res = std::to_chars(buf, buf + size, t);  // points to buffer area it can use. Must be char, not wchar_t, etc.

    if (res.ec == std::errc{}) // no error
    {
        // %.*s provides the exact number of characters to output because the output range, [buf, res.ptr), isn't null-terminated
        printf("success: %.*s\n", static_cast<int>(res.ptr - buf), buf);
    }
    else // probably std::errc::value_too_large
    {
        printf("Error: %d\n", static_cast<int>(res.ec));
    }
}

int main()
{
    TestToChars(123.34);
    return 0;
}

`from_chars`

Convertissez une séquence d’un char entier ou d’une valeur à virgule flottante.

// char to an integer value

from_chars_result from_chars(const char* first, const char* last, char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, signed char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned char& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, short& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned short& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, int& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned int& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, long long& value, int base = 10);
from_chars_result from_chars(const char* first, const char* last, unsigned long long& value, int base = 10);

// char to a floating-point value

from_chars_result from_chars(const char* first, const char* last, float& value, chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, double& value, chars_format fmt = chars_format::general);
from_chars_result from_chars(const char* first, const char* last, long double& value, chars_format fmt = chars_format::general);

Paramètres

first
Pointe vers le début de la mémoire tampon des caractères à convertir.

last
Pointe un au-delà de l’élément de fin de la mémoire tampon de caractères à convertir.

valeur
Si la conversion réussit, contient le résultat de la conversion.

base
Pour les conversions d’entiers, la base à utiliser pendant la conversion. Doit être compris entre 2 et 36, inclus.

Fmt
Pour les conversions à virgule flottante, le format de la séquence de caractères en cours de conversion. Pour plus d’informations, consultez chars_format .

Notes

Les from_chars() fonctions analysent la chaîne [first, last) pour un modèle de nombre, où [first, last) est nécessaire pour être une plage valide.

Lors de l’analyse des caractères, l’espace blanc n’est pas ignoré. Contrairement strtod()à , par exemple, la mémoire tampon doit commencer par une représentation numérique valide.

Retourne une structure from_chars_result.

Si aucun caractère ne correspond à un modèle de nombre, value n’est pas modifié, from_chars_result.ptr pointe vers first, et from_chars_result.ec est errc::invalid_argument.

Si seuls certains caractères correspondent à un modèle de nombre, from_chars_result.ptr pointe vers le premier caractère qui ne correspond pas au modèle ou a la valeur du last paramètre si tous les caractères correspondent.

Si la valeur analysée n’est pas dans la plage représentée par le type de value, value n’est pas modifiée et from_chars_result.ec est errc::result_out_of_range.

Sinon, value est défini sur la valeur analysée, après arrondi, et from_chars_result.ec est égal à errc{}.

Exemple

#include <charconv>
#include <stdio.h>
#include <string_view>
#include <system_error>

double TestFromChars(const std::string_view sv)
{
    const char* const first = sv.data();
    const char* const last = first + sv.size();
    double dbl;

    const std::from_chars_result res = std::from_chars(first, last, dbl);

    if (res.ec == std::errc{}) // no error
    {
        printf("success: %g\n", dbl);
    }
    else
    {
        printf("Error: %d\n", static_cast<int>(res.ec));
    }

    return dbl;
}

int main()
{
    double dbl = TestFromChars("123.34");
    return 0;
}

Spécifications

Header :<charconv>

Espace de noms : std

/std:c++17 ou version ultérieure est nécessaire.

Voir aussi

<charconv>
Chaîne décimale la plus courte que les spécificateurs de format printf()

Partager via

fonctions`<charconv>`

`to_chars`

Paramètres

Valeur retournée

Notes

Exemple

`from_chars`

Paramètres

Notes

Exemple

Spécifications

Voir aussi

Commentaires

Ressources supplémentaires

Partager via

fonctions<charconv>

to_chars

Paramètres

Valeur retournée

Notes

Exemple

from_chars

Paramètres

Notes

Exemple

Spécifications

Voir aussi

Commentaires

Ressources supplémentaires

fonctions`<charconv>`

`to_chars`

`from_chars`