std::to_chars - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::to_chars

From cppreference.com
< cpp‎ | utility

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); 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::error_code 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.

1) Integer formatters: `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`.
2) value is converted to a string as if by std::sprintf 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.
3) same as (2), but the conversion specified for the as-if printf is 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`.
4) same as (3), except the precision is specified by the parameter `precision` rather than by the shortest representation requirement.
5) The return type (see Return value below)

### [edit] 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

### [edit] 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.

### [edit] Exceptions

(none)

### [edit] 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.

### [edit] Example

| This section is incomplete Reason: no example

### [edit] See also

to_string (C++11) | converts an integral or floating point value to `string` (function) [edit]
printffprintfsprintfsnprintf (C++11) | prints formatted output to stdout, a file stream or a buffer (function) [edit]
operator<< | inserts formatted data (public member function of `std::basic_ostream`) [edit]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/utility/to_chars&oldid=92142"
Category:

- Todo no example