Defined in header <charconv> | ||
---|---|---|
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::errc 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
.
std::strtol
in the default ("C") locale and the given non-zero numeric base, except that value
. 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 fmt
has std::chars_format::scientific
set but not std::chars_format::fixed
, the exponent part is required (otherwise it is optional) fmt
has std::chars_format::fixed
set but not std::chars_format::scientific
, the optional exponent is not permitted 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"). std::round_to_nearest
. 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 |
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 value-initialized.
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.
(none).
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 std::to_chars
exactly is only provided if both functions are from the same implementation.
A pattern consisting of a sign with no digits following it is treated as pattern that did not match anything.
#include <iostream> #include <charconv> #include <array> int main() { std::array<char, 10> str{"42"}; int result; if(auto [p, ec] = std::from_chars(str.data(), str.data()+str.size(), result); ec == std::errc()) std::cout << result; }
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 an integer or floating-point value to a character sequence (function) |
(C++11)(C++11)(C++11) | converts a string to a signed integer (function) |
(C++11)(C++11)(C++11) | converts a string to a floating point value (function) |
converts a byte string to an integer value (function) |
|
converts a byte string to a floating point value (function) |
|
reads formatted input from stdin , a file stream or a buffer (function) |
|
extracts formatted data (public member function of std::basic_istream<CharT,Traits> ) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/utility/from_chars