std::from_chars, std::from_chars_result
Defined in header <charconv>
|
||
(1) | ||
std::from_chars_result from_chars( const char* first, const char* last, /*see below*/& value, int base = 10 ); |
(since C++17) (until C++23) |
|
constexpr std::from_chars_result from_chars( const char* first, const char* last, /*see below*/& value, int base = 10 ); |
(since C++23) | |
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, |
(4) | (since C++17) |
Helper types |
||
struct from_chars_result { const char* ptr; |
(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
.
- "0x" or "0X" prefixes are not recognized if
base
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
.- the plus sign is not recognized outside of the exponent (only the minus sign is permitted at the beginning)
- 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") - leading whitespace is not ignored.
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-test macro: | __cpp_lib_to_chars |
Feature-test macro: | __cpp_lib_constexpr_charconv |
Example
#include <cassert> #include <charconv> #include <iomanip> #include <iostream> #include <optional> #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"; } } // C++23's constexpr from_char demo: auto to_int = [](std::string_view s) -> std::optional<int> { if (int value; std::from_chars(s.begin(), s.end(), value).ec == std::errc{}) return value; else return std::nullopt; }; assert(to_int("42") == 42); assert(to_int("foo") == std::nullopt); #if __cpp_lib_constexpr_charconv and __cpp_lib_optional >= 202106 static_assert(to_int("42") == 42); static_assert(to_int("foo") == std::nullopt); #endif }
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> ) |