std::to_chars, std::to_chars_result

std::to_chars_result to_chars( char* first, char* last,
                               /*see below*/ value, int base = 10 );

constexpr std::to_chars_result to_chars( char* first, char* last,
                               /*see below*/ value, int base = 10 );

std::to_chars_result to_chars( char*, char*, bool, int = 10 ) = delete;

std::to_chars_result to_chars( char* first, char* last, float       value );
std::to_chars_result to_chars( char* first, char* last, double      value );
std::to_chars_result to_chars( char* first, char* last, long double value );

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

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

struct to_chars_result {
    char* ptr;
    std::errc ec;
};

Converts value into a character string by successively filling the range [first, last), where [first, last) is required to be a valid range.

Parameters

Return value

On success, returns a value of type to_chars_result such that ec equals value-initialized std::errc and ptr is the one-past-the-end pointer of the characters written. Note that the string is not NUL-terminated.

On error, returns a value of type to_chars_result holding std::errc::value_too_large in ec, a copy of the value last in ptr, and leaves the contents of the range [first, last) in unspecified state.

friend bool operator==( const to_chars_result&, const to_chars_result& ) = default;

Exceptions

Throws nothing.

Notes

Unlike other formatting functions in C++ and C libraries, std::to_chars is locale-independent, non-allocating, and non-throwing. Only a small subset of formatting policies used by other libraries (such as std::sprintf) is provided. This is intended to allow the fastest possible implementation that is useful in common high-throughput contexts such as text-based interchange (JSON or XML).

The guarantee that std::from_chars can recover every floating-point value formatted by to_chars exactly is only provided if both functions are from the same implementation.

It is required to explicitly cast a bool value to another integer type if it is wanted to format the value as "0"/"1".

Example

#include <array>
#include <charconv>
#include <iostream>
#include <string_view>
#include <system_error>
 
void show_to_chars(auto... format_args)
{
    std::array<char, 10> str;
 
    if(auto [ptr, ec] = std::to_chars(str.data(), str.data() + str.size(), format_args...);
       ec == std::errc())
    {
        std::cout << std::string_view
            (str.data(), ptr) << '\n';
        //  (str.data(), ptr - str.data()) // C++17 alt, using string_view(ptr, length)
    }
    else
    {
        std::cout << std::make_error_code(ec).message() << '\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);
}

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

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also