std::to_chars

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

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.

Exceptions

(none).

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.

Example

#include <iostream>
#include <charconv>
#include <system_error>
#include <string_view>
#include <array>
 
int main()
{
    std::array<char, 10> str;
 
    if(auto [p, ec] = std::to_chars(str.data(), str.data() + str.size(), 42);
       ec == std::errc())
        std::cout << std::string_view(str.data(), p - str.data());
}

42

Defect reports

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

See also