funciones`<charconv>`

Artículo
06/16/2023

El encabezado <charconv> incluye las siguientes funciones no miembro:

Funciones no miembro	Descripción
to_chars	Convierte un valor entero o de punto flotante en una secuencia de `char`.
from_chars	Convierte una secuencia de `char` en un valor entero o de punto flotante.

Estas funciones de conversión están optimizadas para el rendimiento y también admiten el comportamiento de ida y vuelta más cortas. El comportamiento de ida y vuelta más cortas significa que cuando un número se convierte en caracteres, solo se escribe la precisión suficiente para permitir recuperar el número original al convertir esos caracteres de nuevo en un punto flotante.

Al convertir caracteres en un número, el valor numérico no necesita terminar en NULL. Del mismo modo, al convertir un número en caracteres, el resultado no termina en NULL.
Las funciones de conversión no asignan memoria. Posee el búfer en todos los casos.
Las funciones de conversión no se inician. Se devuelve un resultado del que se puede determinar si la conversión se realizó correctamente.
Las funciones de conversión no distinguen el modo de redondeo en tiempo de ejecución.
Las funciones de conversión no reconocen la configuración regional. Siempre imprimen y analizan los puntos decimales como '.' y nunca como "," para las configuraciones regionales que usan comas.

`to_chars`

Convierte un valor entero o de punto flotante en una secuencia de char.

Convierte value en una cadena de caracteres rellenando el intervalo [first, last), donde [first, last) debe ser un intervalo válido. Devuelve una estructura to_chars_result. Si la conversión se realiza correctamente, como se indica en to_char_result.ec, el miembro ptr es el puntero de un solo extremo de los caracteres escritos. De lo contrario, to_char_result.ec tiene el valor errc::value_too_large, to_char_result.ptr tiene el valor last y no se especifica el contenido del intervalo [first, last).

La única manera en que to_chars puede producir un error si proporciona un búfer que no es suficientemente grande para contener el 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
Puntos al principio del búfer que se va a rellenar.

last
Apunta un carácter más allá del final del búfer que se va a rellenar.

value
Valor que se va a convertir. Si value es negativo, la representación comienza por -.

base
Para las conversiones de enteros, la base que se va a usar al convertir value en caracteres. Debe tener un valor comprendido entre 2 y 36, ambos inclusive. No habrá ceros iniciales. Los dígitos del intervalo 10..35 (ambos inclusive) se representan como caracteres en minúsculas a...z.

fmt
En el caso de las conversiones de punto flotante, una máscara de bits que especifica el formato de conversión que se va a usar, como científico, fijo o hexadecimal. Vea chars_format para obtener más detalles.

precisión
Para las conversiones de punto flotante, el número de dígitos de precisión para el valor convertido.

Valor devuelto

to_chars_result que contiene el resultado de la conversión.

Comentarios

Las funciones que toman un parámetro chars_format determinan el especificador de conversión como si estuvieran usando printf() de la siguiente manera: el especificador de conversión es si es 'f', si fmt es chars_format::fixed; 'e' si fmt es chars_format::scientific; 'a' (sin 0x en el resultado inicial) si fmt es chars_format::hex; y 'g' si fmt es chars_format::general. Especificar la notación fija más corta puede dar lugar a una salida larga porque puede ser la representación más corta posible cuando el valor es muy grande o muy pequeño.

En la tabla siguiente se describe el comportamiento de conversión dadas diferentes combinaciones de los parámetros fmt y precision. El término "comportamiento de ida y vuelta más cortas" hace referencia a escribir el menor número de dígitos necesarios para que el análisis de esa representación usando la función correspondiente from_chars recupere el valor exactamente.

Combinación de `fmt` y `precision`	Output
Neither	Cualquiera de las notaciones fijas o científicas es más corta, y se prefiere la fija como desempate. Este comportamiento no se puede simular mediante ninguna sobrecarga que tome el parámetro `fmt`.
`fmt`	Comportamiento de ida y vuelta más cortas para el formato especificado, como el formato científico más corto.
`fmt` y `precision`	Usa la precisión dada, siguiendo el estilo `printf()`, sin un comportamiento de ida y vuelta más cortas.

Ejemplo

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

Convierte una secuencia de char en un valor entero o de punto flotante.

// 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
Apunta al principio del búfer de caracteres que se va a convertir.

last
Apunta a un elemento más allá del último del búfer de caracteres que se va a convertir.

value
Si la conversión se realiza correctamente, contiene el resultado de la conversión.

base
Para las conversiones de enteros, la base que se va a usar durante la conversión. Debe tener un valor comprendido entre 2 y 36, ambos inclusive.

fmt
Para las conversiones de punto flotante, el formato de la secuencia de caracteres que se va a convertir. Vea chars_format para obtener más detalles.

Comentarios

Las funciones from_chars() analizan la cadena [first, last) para un patrón numérico, donde [first, last) debe ser un intervalo válido.

Al analizar caracteres, no se omite el espacio en blanco. A diferencia de strtod(), por ejemplo, el búfer debe comenzar con una representación numérica válida.

Devuelve una estructura m_chars_result.

Si no hay caracteres que coincidan con un patrón de número, value no se modifica, from_chars_result.ptr apunta a first y from_chars_result.ec es errc::invalid_argument.

Si solo algunos caracteres coinciden con un patrón de número, from_chars_result.ptr apunta al primer carácter que no coincide con el patrón o tiene el valor del parámetro last si coinciden todos los caracteres.

Si el valor analizado no está en el intervalo que representa el tipo de value, value no se modifica y from_chars_result.ec es errc::result_out_of_range.

De lo contrario, value se establece en el valor analizado, después del redondeo, y from_chars_result.ec es igual a errc{}.

Ejemplo

#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

Encabezado:<charconv>

Espacio de nombres: std

Se requiere /std:c++17 o posterior.

Consulte también

<charconv>
La cadena decimal más corta que los especificadores de formato printf() de ida y vuelta

Compartir a través de

funciones`<charconv>`

`to_chars`

Parámetros

Valor devuelto

Comentarios

Ejemplo

`from_chars`

Parámetros

Comentarios

Ejemplo

Requisitos

Consulte también

Comentarios

Recursos adicionales

Compartir a través de

funciones<charconv>

to_chars

Parámetros

Valor devuelto

Comentarios

Ejemplo

from_chars

Parámetros

Comentarios

Ejemplo

Requisitos

Consulte también

Comentarios

Recursos adicionales

funciones`<charconv>`

`to_chars`

`from_chars`