Difference between revisions of "cpp/utility/to chars"

Revision as of 18:02, 9 August 2021

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

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 <iostream>
#include <charconv>
#include <system_error>
#include <string_view>
#include <array>
 
int main()
{
    std::array<char, 10> str;
 
    if(auto [ptr, ec] = std::to_chars(str.data(), str.data() + str.size(), 42);
       ec == std::errc())
         std::cout << std::string_view
           (str.data(), ptr);              // C++20, uses string_view(first, last)
      //   (str.data(), ptr - str.data()); // C++17, uses string_view(ptr, length)
}

42

Defect reports

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

See also