`<charconv>` funzioni

Articolo
10/12/2023

L'intestazione <carbonnv> include le funzioni non membro seguenti:

Funzioni non membro	Descrizione
to_chars	Convertire un valore intero o a virgola mobile in una sequenza di `char`.
from_chars	Convertire una sequenza di `char` in un valore intero o a virgola mobile.

Queste funzioni di conversione sono ottimizzate per le prestazioni e supportano anche il comportamento di round trip più breve. Il comportamento di round trip più breve indica quando un numero viene convertito in caratteri, viene scritta solo una precisione sufficiente per consentire il recupero del numero originale durante la conversione di tali caratteri in un carattere a virgola mobile.

Quando si converte chars in un numero, il valore numerico non deve essere terminato con null. Analogamente, quando si converte un numero in caratteri, il risultato non viene terminato con null.
Le funzioni di conversione non allocano memoria. Si è proprietari del buffer in tutti i casi.
Le funzioni di conversione non generano un'eccezione. Viene restituito un risultato da cui è possibile determinare se la conversione è riuscita.
Le funzioni di conversione non sono sensibili alla modalità di arrotondamento in fase di esecuzione.
Le funzioni di conversione non sono in grado di conoscere le impostazioni locali. Stampano e analizzano sempre i punti decimali come '.'e mai come "", per le impostazioni locali che usano virgole.

`to_chars`

Convertire un valore intero o a virgola mobile in una sequenza di char.

Converte value in una stringa di caratteri riempiendo l'intervallo [, last), dove [firstfirst, last) deve essere un intervallo valido. Restituisce una struttura to_chars_result. Se la conversione ha esito positivo, come indicato da to_char_result.ec, il membro ptr è il puntatore uno-passato-finale dei caratteri scritti. In caso contrario, to_char_result.ec ha il valore , to_char_result.ptr ha il valore lasterrc::value_too_largee il contenuto dell'intervallo [first, last) non sono specificati.

L'unico modo che to_chars può avere esito negativo è se si specifica un buffer di dimensioni insufficienti per contenere il risultato.

// 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);

Parametri

first
Punta all'inizio del buffer da riempire.

last
Punta un carattere oltre la fine del buffer da riempire.

value
Valore da convertire. Se value è negativo, la rappresentazione inizia con -.

base
Per le conversioni integer, la base da utilizzare per la conversione value in caratteri. Deve essere compreso tra 2 e 36 inclusi. Non ci saranno zeri iniziali. Le cifre nell'intervallo 10..35 (incluse) sono rappresentate come caratteri minuscoli a.. z

Fmt
Per le conversioni a virgola mobile, maschera di bit che specifica il formato di conversione da usare, ad esempio scientifico, fisso o esadecimale. Per informazioni dettagliate, vedere chars_format .

precision
Per le conversioni a virgola mobile, il numero di cifre di precisione per il valore convertito.

Valore restituito

Oggetto to_chars_result contenente il risultato della conversione.

Osservazioni:

Le funzioni che accettano un parametro chars_format determinano l'identificatore di conversione come se fossero in uso printf() come segue: l'identificatore di conversione è se è 'f' , se fmt fmt è chars_format::scientificchars_format::fixed, 'a' 'e' (senza l'iniziale 0x nel risultato) se fmt è chars_format::hexe 'g' se fmt è chars_format::general. La specifica della notazione fissa più breve può comunque comportare un output lungo perché può essere la rappresentazione più breve possibile quando il valore è molto grande o molto piccolo.

Nella tabella seguente viene descritto il comportamento di conversione in base a diverse combinazioni di fmt parametri e precision . Il termine "comportamento di round trip più breve" si riferisce alla scrittura del minor numero di cifre necessarie, in modo che l'analisi della rappresentazione tramite la funzione corrispondente from_chars recupererà esattamente il valore.

`fmt` e `precision` combinazione	Output
Nessuno	Qualunque sia la notazione fissa o scientifica è più breve, preferendo fissa come tiebreaker. Questo comportamento non può essere simulato da alcun overload che accetta il `fmt` parametro .
`fmt`	Il comportamento di round trip più breve per il formato specificato, ad esempio il formato scientifico più breve.
`fmt` e `precision`	Usa la precisione specificata, il seguente `printf()` stile, senza il comportamento di round trip più breve.

Esempio

#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`

Convertire una sequenza di char in un valore intero o a virgola mobile.

// 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);

Parametri

first
Punta all'inizio del buffer di caratteri da convertire.

last
Punta uno oltre l'elemento finale del buffer di caratteri da convertire.

value
Se la conversione ha esito positivo, contiene il risultato della conversione.

base
Per le conversioni integer, la base da utilizzare durante la conversione. Deve essere compreso tra 2 e 36 inclusi.

Fmt
Per le conversioni a virgola mobile, il formato della sequenza di caratteri da convertire. Per informazioni dettagliate, vedere chars_format .

Osservazioni:

Le from_chars() funzioni analizzano la stringa [first, last) per un criterio numerico, dove [first, last) deve essere un intervallo valido.

Durante l'analisi dei caratteri, gli spazi vuoti non vengono ignorati. A differenza di strtod(), ad esempio, il buffer deve iniziare con una rappresentazione numerica valida.

Restituisce una struttura from_chars_result.

Se nessun carattere corrisponde a un criterio numerico, value viene modificato, from_chars_result.ptr punta a firste from_chars_result.ec è errc::invalid_argument.

Se solo alcuni caratteri corrispondono a un criterio numerico, from_chars_result.ptr punta al primo carattere che non corrisponde al criterio oppure ha il valore del last parametro se tutti i caratteri corrispondono.

Se il valore analizzato non è incluso nell'intervallo rappresentabile dal tipo di value, value non è modificato e from_chars_result.ec è errc::result_out_of_range.

In caso contrario, value è impostato sul valore analizzato, dopo l'arrotondamento ed from_chars_result.ec è uguale a errc{}.

Esempio

#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;
}

Requisiti

Intestazione:<carbonnv>

Spazio dei nomi: std

/std:c++17 o versione successiva è obbligatoria.

Vedi anche

<carbonnv>
Stringa decimale più breve che esegue il round trip degli identificatori di formato printf()

Condividi tramite

`<charconv>` funzioni

`to_chars`

Parametri

Valore restituito

Osservazioni:

Esempio

`from_chars`

Parametri

Osservazioni:

Esempio

Requisiti

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

<charconv> funzioni

to_chars

Parametri

Valore restituito

Osservazioni:

Esempio

from_chars

Parametri

Osservazioni:

Esempio

Requisiti

Vedi anche

Commenti e suggerimenti

Risorse aggiuntive

`<charconv>` funzioni

`to_chars`

`from_chars`