std::to_chars
Defined in header <utility>
|
||
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); |
(2) | (since C++17) |
std::to_chars_result to_chars(char* first, char* last, float 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); |
(4) | (since C++17) |
struct to_chars_result { char* ptr; |
(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
.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.Parameters
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 |
Return value
On success, returns a value of type to_chars_result
such that ec
is false
when converted to bool
and ptr
is the one-past-the-end pointer of the characters written.
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
This section is incomplete Reason: no example |
See also
(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 ) |