Namespaces
Variants

std:: to_chars

From cppreference.net
C++
Text processing library
Definido en el encabezado <charconv>
std :: to_chars_result

to_chars ( char * first, char * last,

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

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

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

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

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

Convierte value en una cadena de caracteres llenando sucesivamente el rango [ first , last ) , donde [ first , last ) debe ser un rango válido .

1) Formateadores de enteros: value se convierte en una cadena de dígitos en la base dada (sin ceros iniciales redundantes). Los dígitos en el rango 10..35 (inclusive) se representan como caracteres en minúscula a..z . Si value es menor que cero, la representación comienza con un signo menos. La biblioteca proporciona sobrecargas para todos los tipos enteros con y sin signo sin calificadores cv y para el tipo char como el tipo del parámetro value .
2) La sobrecarga para bool está eliminada. std::to_chars rechaza argumentos de tipo bool porque el resultado sería "0" / "1" y no "false" / "true" si estuviera permitido.
3) value se convierte a una cadena en el estilo de std::printf en la configuración regional predeterminada ("C"). El especificador de conversión es f o e (resolviendo a favor de f en caso de empate), elegido según el requisito de representación más corta: la representación en cadena consiste en el menor número de caracteres tal que haya al menos un dígito antes del punto decimal (si está presente) y analizando la representación usando la función correspondiente std::from_chars recupera el valor exactamente. Si hay varias representaciones de este tipo, se elige aquella con la menor diferencia respecto a value , resolviendo cualquier empate restante mediante redondeo según std::round_to_nearest . La biblioteca proporciona sobrecargas para todos los tipos de punto flotante estándar (until C++23) sin calificadores cv como tipo del parámetro value .
4) Igual que (3) , pero la conversión especificada para el printf as-if es f si fmt es std::chars_format::fixed , e si fmt es std::chars_format::scientific , a (pero sin el "0x" inicial en el resultado) si fmt es std::chars_format::hex , y g si fmt es chars_format::general . La biblioteca proporciona sobrecargas para todos los tipos estándar (hasta C++23) de punto flotante sin calificadores cv como tipo del parámetro value .
5) Igual que (4) , excepto que la precisión se especifica mediante el parámetro precision en lugar de por el requisito de representación más corta. La biblioteca proporciona sobrecargas para todos los tipos estándar (hasta C++23) de punto flotante sin calificación cv como tipo del parámetro value .

Contenidos

Parámetros

first, last - rango de caracteres a escribir
value - valor a convertir a su representación de cadena
base - base entera a utilizar: un valor entre 2 y 36 (inclusive).
fmt - formato de punto flotante a utilizar, una máscara de bits de tipo std::chars_format
precision - precisión de punto flotante a utilizar

Valor de retorno

En caso de éxito, retorna un valor de tipo std::to_chars_result tal que ec es igual a un valor inicializado por defecto de std::errc y ptr es el puntero que apunta después del último carácter escrito. Nótese que la cadena no está terminada en NUL.

En caso de error, retorna un valor de tipo std::to_chars_result que contiene std::errc::value_too_large en ec , una copia del valor last en ptr , y deja el contenido del rango [ first , last ) en un estado no especificado.

Excepciones

No lanza nada.

Notas

A diferencia de otras funciones de formato en las bibliotecas de C++ y C, std::to_chars es independiente de la configuración regional, no asigna memoria y no lanza excepciones. Solo se proporciona un pequeño subconjunto de políticas de formato utilizadas por otras bibliotecas (como std::sprintf ). Esto está diseñado para permitir la implementación más rápida posible que sea útil en contextos comunes de alto rendimiento como el intercambio basado en texto ( JSON o XML ).

La garantía de que std::from_chars puede recuperar cada valor de punto flotante formateado por std::to_chars exactamente solo se proporciona si ambas funciones son de la misma implementación.

Para formatear un valor bool como "0" / "1" usando std::to_chars , el valor debe convertirse a otro tipo entero.

Macro de prueba de características Valor Std Característica
__cpp_lib_to_chars 201611L (C++17) Conversiones elementales de cadenas ( std::to_chars , std::from_chars )
202306L (C++26) Prueba de éxito o fallo de funciones de <charconv>
__cpp_lib_constexpr_charconv 202207L (C++23) Añadir modificadores constexpr a las sobrecargas de std::to_chars y std::from_chars ( 1 ) para tipos integrales

Ejemplo

Ejecutar este código 
#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);
}

Salida posible: 

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

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares publicados anteriormente de C++.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 2955 C++17 esta función estaba en <utility> y usaba std::error_code movida a <charconv> y usa std::errc
LWG 3266 C++17 bool argumento era aceptado y promovido a int rechazado por una sobrecarga eliminada
LWG 3373 C++17 std::to_chars_result podría tener miembros adicionales se prohíben miembros adicionales

Véase también

(C++17)
el tipo de retorno de std::to_chars
(clase)
(C++17)
convierte una secuencia de caracteres a un valor entero o de punto flotante
(función)
(C++11)
convierte un valor entero o de punto flotante a string
(función)
(C++11)
imprime salida formateada a stdout , un flujo de archivo o un búfer
(función)
inserta datos formateados
(función miembro pública de std::basic_ostream<CharT,Traits> )