Defined in header <charconv> | ||
---|---|---|
std::to_chars_result to_chars(char* first, char* last, /*see below*/ value, int base = 10); | (1) | (since C++17) |
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); | (2) | (since C++17) |
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); | (3) | (since C++17) |
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); | (4) | (since C++17) |
struct to_chars_result { char* ptr; std::errc ec; }; | (5) | (since C++17) |
Converts value
into a character string by successively filling the range [first, last)
, where [first, last)
is required to be a valid range.
value
is converted to a string of digits in the given base
(with no redundant leading zeroes). Digits in the range 10..35
(inclusive) are represented as lowercase characters a..z
. If value is less than zero, the representation starts with a minus sign. The library provides overloads for all signed and unsigned integer types and for the type char
as the type of the parameter value
.std::printf
in the default ("C") locale. The conversion specifier is f
or e
(resolving in favor of f
in case of a tie), chosen according to the requirement for a shortest representation: the string representation consists of the smallest number of characters such that there is at least one digit before the radix point (if present) and parsing the representation using the corresponding std::from_chars
function recovers value exactly. If there are several such representations, one with the smallest difference to value
is chosen, resolving any remaining ties using rounding according to std::round_to_nearest
f
if fmt
is std::chars_format::fixed
, e
if fmt
is std::chars_format::scientific
, a
(but without leading "0x" in the result) if fmt
is std::chars_format::hex
, and g
if fmt
is chars_format::general
.precision
rather than by the shortest representation requirement.first, last | - | character range to write to |
value | - | the value to convert to its string representation |
base | - | integer base to use: a value between 2 and 36 (inclusive). |
fmt | - | floating-point formatting to use, a bitmask of type std::chars_format |
precision | - | floating-point precision to use |
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.
(none).
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.
#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()); }
Output:
42
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 2955 | C++17 | this function was in <utility> and used std::error_code | moved to <charconv> and uses std::errc |
(C++17) | converts a character sequence to an integer or floating-point value (function) |
(C++11) | converts an integral or floating point value to string (function) |
(C++11) | prints formatted output to stdout , a file stream or a buffer (function) |
inserts formatted data (public member function of std::basic_ostream<CharT,Traits> ) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/utility/to_chars