Funções `<charconv>`

Artigo
06/16/2023

O cabeçalho <charconv> inclui as seguintes funções não membro:

Funções de não membro	Descrição
to_chars	Converter um valor inteiro ou de ponto flutuante em uma sequência de `char`.
from_chars	Converter uma sequência de `char` para um valor inteiro ou de ponto flutuante.

Essas funções de conversão são ajustadas para o desempenho e dão suporte ao comportamento de ida e volta mais curto. O comportamento de ida e volta mais curto significa que quando um número é convertido em caracteres, somente a precisão suficiente é gravada para permitir a recuperação do número original ao converter esses caracteres de volta em um ponto flutuante.

Ao converter caracteres em um número, o valor numérico não precisa ser terminado em nulo. Da mesma forma, ao converter um número em caracteres, o resultado não é terminado em nulo.
As funções de conversão não alocam memória. Você possui o buffer em todos os casos.
As funções de conversão não são lançadas. Um resultado é retornado, com base no qual você pode determinar se a conversão foi bem-sucedida.
As funções de conversão não são sensíveis ao modo de arredondamento de runtime.
As funções de conversão não estão cientes da localidade. Eles sempre imprimem e analisam pontos decimais como '.', e nunca como "", para localidades que usam vírgulas.

`to_chars`

Converter um valor inteiro ou de ponto flutuante em uma sequência de char.

Converte value em uma cadeia de caracteres preenchendo o intervalo [first, last), em que [first, last) deve ser um intervalo válido. Retorna uma estrutura to_chars_result. Se a conversão for bem-sucedida, conforme indicado por to_char_result.ec, o membro ptr será o ponteiro depois do fim dos caracteres gravados. Caso contrário, to_char_result.ec tem o valor errc::value_too_large, to_char_result.ptr tem o valor laste o conteúdo do intervalo [first, last) não é especificado.

A única maneira de to_chars falhar é se você fornecer um buffer insuficientemente grande para manter o resultado.

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

Parâmetros

first
Aponta para o início do buffer para preenchimento.

last
Aponta para um caractere depois do fim do buffer para preenchimento.

value
O valor a ser convertido. Se value for negativo, a representação começará com -.

base
Para conversões de inteiro, a base a ser usada ao converter value em caracteres. Deve estar entre 2 e 36, inclusivo. Não haverá zeros à esquerda. Os dígitos no intervalo 10..35 (inclusivo) são representados como caracteres minúsculos a..z

fmt
Para conversões de ponto flutuante, um bitmask que especifica o formato de conversão a ser usado, como científico, fixo ou hexadecimal. Confira chars_format para obter detalhes.

precisão
Para conversões de ponto flutuante, o número de dígitos de precisão para o valor convertido.

Valor retornado

Um to_chars_result que contém o resultado da conversão.

Comentários

As funções que usam um parâmetro chars_format determinam o especificador de conversão como se estivessem usando printf() da seguinte maneira: o especificador de conversão é 'f', fmt se for chars_format::fixed, 'e' se fmt for chars_format::scientific, 'a' (sem o 0x líder no resultado) se fmt for chars_format::hex, e 'g' se fmt for chars_format::general. Especificar a notação fixa mais curta ainda pode resultar em uma saída demorada porque pode ser a menor representação possível quando o valor é muito grande ou muito pequeno.

A tabela a seguir descreve o comportamento de conversão, considerando combinações de parâmetros fmt e precision diferentes. O termo "comportamento de ida e volta mais curto" refere-se à gravação do menor número de dígitos necessários, de modo que analisar essa representação usando a função correspondente from_chars recuperará exatamente o valor.

Combinação de `fmt` e `precision`	Saída
Nenhum	A notação mais curta, seja fixa ou científica. No caso de empate, a preferência é a fixa. Esse comportamento não pode ser simulado por qualquer sobrecarga que use o parâmetro `fmt`.
`fmt`	O comportamento de ida e volta mais curto para o formato especificado, como o formato científico mais curto.
`fmt` e `precision`	Usa a precisão fornecida, seguindo o estilo `printf()`, sem o comportamento de ida e volta mais curto.

Exemplo

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

Converter uma sequência de char para um valor inteiro ou de ponto flutuante.

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

Parâmetros

first
Aponta para o início do buffer de caracteres para converter.

last
Aponta o elemento depois do fim do buffer de caracteres para converter.

value
Se a conversão for bem-sucedida, ela conterá o resultado da conversão.

base
Para conversões de inteiro, a base a ser usada durante a conversão. Deve estar entre 2 e 36, inclusivo.

fmt
Para conversões de ponto flutuante, o formato da sequência de caracteres que está sendo convertida. Confira chars_format para obter detalhes.

Comentários

As funções from_chars() analisam a cadeia de caracteres [first, last) para um padrão de números, em que [first, last) é necessário para ser um intervalo válido.

Ao analisar caracteres, o espaço em branco não é ignorado. Ao contrário de strtod(), por exemplo, o buffer deve começar com uma representação numérica válida.

Retorna uma estrutura to_chars_result.

Se nenhum caractere corresponder a um padrão numérico, value não será modificado, from_chars_result.ptr apontará para firste from_chars_result.ec será errc::invalid_argument.

Se apenas alguns caracteres corresponderem a um padrão numérico, from_chars_result.ptr apontará para o primeiro caractere que não corresponde ao padrão, ou terá o valor do parâmetro last se todos os caracteres corresponderem.

Se o valor analisado não estiver no intervalo representável pelo tipo de value, value será não modificado e from_chars_result.ec será errc::result_out_of_range.

Caso contrário, value será definido como o valor analisado, após o arredondamento, e from_chars_result.ec será igual a errc{}.

Exemplo

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

Requisitos

Cabeçalho:<charconv>

Namespace: std

/std:c++17 ou posterior é necessário.

Confira também

<charconv>
A cadeia de caracteres decimal mais curta que os especificadores de formato printf() de ida e volta

Partilhar via

Funções `<charconv>`

`to_chars`

Parâmetros

Valor retornado

Comentários

Exemplo

`from_chars`

Parâmetros

Comentários

Exemplo

Requisitos

Confira também

Comentários

Recursos adicionais

Partilhar via

Funções <charconv>

to_chars

Parâmetros

Valor retornado

Comentários

Exemplo

from_chars

Parâmetros

Comentários

Exemplo

Requisitos

Confira também

Comentários

Recursos adicionais

Funções `<charconv>`

`to_chars`

`from_chars`