std::from_chars, std::from_chars_result
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) |
Helper types | ||
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
-
"0x"
or"0X"
prefixes are not recognized ifbase
is 16 - only the minus sign is recognized (not the plus sign), and only for signed integer types of
value
- leading whitespace is not ignored.
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 outside of the exponent (only the minus sign is permitted at the beginning)
- if
fmt
hasstd::chars_format::scientific
set but notstd::chars_format::fixed
, the exponent part is required (otherwise it is optional) - if
fmt
hasstd::chars_format::fixed
set but notstd::chars_format::scientific
, the optional exponent is not permitted - if
fmt
isstd::chars_format::hex
, the prefix"0x"
or"0X"
is not permitted (the string"0x123"
parses as the value"0"
with unparsed remainder"x123"
) - leading whitespace is not ignored.
std::round_to_nearest
.
std::from_chars_result
has no base classes, or members other than
ptr
,
ec
and implicitly declared special member functions.
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 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.
operator==(std::from_chars_result)
friend bool operator==( const from_chars_result&, const from_chars_result& ) = default; |
(since C++20) |
Checks if ptr
and ec
of both arguments are equal respectively.
This function is not visible to ordinary unqualified or qualified lookup, and can only be found by argument-dependent lookup when std::from_chars_result
is an associated class of the arguments.
The !=
operator is synthesized from operator==
.
Exceptions
Throws nothing.
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 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.
Feature testing macro: __cpp_lib_to_chars
.
Example
#include <charconv> #include <iomanip> #include <iostream> #include <string_view> #include <system_error> int main() { for (std::string_view const str : {"1234", "15 foo", "bar", " 42", "5000000000"}) { std::cout << "String: " << std::quoted(str) << ". "; int result{}; auto [ptr, ec] { std::from_chars(str.data(), str.data() + str.size(), result) }; if (ec == std::errc()) { std::cout << "Result: " << result << ", ptr -> " << std::quoted(ptr) << '\n'; } else if (ec == std::errc::invalid_argument) { std::cout << "That isn't a number.\n"; } else if (ec == std::errc::result_out_of_range) { std::cout << "This number is larger than an int.\n"; } } }
Possible output:
String: "1234". Result: 1234, ptr -> "" String: "15 foo". Result: 15, ptr -> " foo" String: "bar". That isn't a number. String: " 42". That isn't a number. String: "5000000000". This number is larger than an int.
Defect reports
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 |
LWG 3373 | C++17 | from_chars_result might have additional members |
additional members are disallowed |
See also
(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) |
(C++11)
|
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.
https://en.cppreference.com/w/cpp/utility/from_chars