# std::from_chars

From cppreference.com
< cpp‎ | utility

Defined in header `<utility>` |  |
std::from_chars_result from_chars(const char* first, const char* last, /*see below*/& value, int base = 10); | (1) | (since C++17)
std::from_chars_result from_chars(const char* first, const char* last, float& value, std::chars_format fmt = std::chars_format::general); | (2) | (since C++17)
std::from_chars_result from_chars(const char* first, const char* last, double& value, std::chars_format fmt = std::chars_format::general); | (3) | (since C++17)
std::from_chars_result from_chars(const char* first, const char* last, long double& value, std::chars_format fmt = std::chars_format::general); | (4) | (since C++17)
struct from_chars_result { const char* ptr; std::error_code ec; }; | (5) | (since C++17)

Analyzes the character sequence `[first,last)` for a pattern described below. If no characters match the pattern or if the value obtained by parsing the matched characters is not representable in the type of `value`, `value` is unmodified, otherwise the characters matching the pattern are interpreted as a text representation of an arithmetic value, which is stored in `value`.

1) Integer parsers: Expects the pattern identical to the one used by std::strtol in the default ("C") locale and the given non-zero numeric base, except that "0x" or "0X" prefixes are not recognized for base 16, and that only the minus sign is recognized (not the plus sign), and only for signed integer types of `value`. Digits in the range `10..35` (inclusive) are represented as lowercase characters `a..z` (uppercase digits are not recognized). The library provides overloads for all signed and unsigned integer types and `char` as the referenced type of the parameter `value`.
2-4) Floating-point parsers: Expects the pattern identical to the one used by std::strtod in the default ("C") locale, except that

- the plus sign is not recognized (only the minus sign is permitted)
- if `fmt` has `std::chars_format::scientific` set but not `std::chars_format::fixed`, the exponent part is required (otherwise it is optional)
- if `fmt` has `std::chars_format::fixed` set but not `std::chars_format::scientific`, the optional exponent is not permitted
- if `fmt` is `std::chars_format::hex`, the prefix "0x" or "0X" is not permitted (the string "0x123" parses as the value "0" with unparsed remainder "x123").

In any case, the resulting value is one of at most two floating-point values closest to the value of the string matching the pattern.
5) The return type (see Return value below)

### Parameters

first, last | - | valid character range to parse
value | - | the out-parameter where the parsed value is stored if successful
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`

### Return value

On success, returns a value of type `from_chars_result` such that `ptr` points at the first character not matching the pattern, or has the value equal to `last` if all characters match and `ec` is `false` when converted to `bool`.

If there is no pattern match, returns a value of type `from_chars_result` such that `ptr` equals `first` and `ec` equals std::errc::invalid_argument. `value` is unmodified.

If the pattern was matched, but the parsed value is not in the range representable by the type of `value`, returns value of type `from_chars_result` such that `ec` equals std::errc::result_out_of_range and `ptr` points at the first character not matching the pattern. `value` is unmodified.

### Exceptions

(none)

### Notes

Unlike other parsing functions in C++ and C libraries, `std::from_chars` is locale-independent, non-allocating, and non-throwing. Only a small subset of parsing policies used by other libraries (such as std::sscanf) 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

stoi stol stoll (C++11)(C++11)(C++11) | converts a string to a signed integer (function)
stof stod stold (C++11)(C++11)(C++11) | converts a string to a floating point value (function)
strtol strtoll | converts a byte string to an integer value (function)
strtof strtod strtold | converts a byte string to a floating point value (function)
scanf fscanf sscanf | reads formatted input from stdin, a file stream or a buffer (function)
operator>> | extracts formatted data (public member function of `std::basic_istream`)

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

- Todo no example