From cppreference.com
Defined in header
std::from_chars_resultfrom_chars(constchar*first,constchar*last,/* integer-type */&value,intbase=10); (1) (since C++17)
(constexpr since C++23)std::from_chars_resultfrom_chars(constchar*first,constchar*last,/* floating-point-type */&value,std::chars_formatfmt=std::chars_format::general); (2) (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
in the default ("C") locale and the given non-zero numeric base, except that
"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.
The library provides overloads for all cv-unqualified(since C++23) signed and unsigned integer types and char as the referenced type of the parameter value.
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, after rounding according to
.
The library provides overloads for all cv-unqualified standard(until C++23) floating-point types as the referenced type of the parameter value.
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
Return value
On success, returns a value of type
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
such that ptr equals first and ec equals
. 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
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
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
) is provided. This is intended to allow the fastest possible implementation that is useful in common high-throughput contexts such as text-based interchange (
or
).
The guarantee that std::from_chars can recover every floating-point value formatted by
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.
macro ValueStdFeature
(C++17)Elementary string conversions (std::from_chars,
)
(C++26)Testing for success or failure of
functions
(C++23)Add constexpr modifiers to std::from_chars and
overloads for integral types Example
Run this code
#include<cassert>#include<charconv>#include<iomanip>#include<iostream>#include<optional>#include<string_view>#include<system_error>intmain(){for(std::string_viewconststr:{"1234","15 foo","bar"," 42","5000000000"}){std::cout<<"String: "<<std::quoted(str)<<". ";intresult{};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';elseif(ec==std::errc::invalid_argument)std::cout<<"This is not a number.\n";elseif(ec==std::errc::result_out_of_range)std::cout<<"This number is larger than an int.\n";}// C++23's constexpr from_char demo / C++26's operator bool() demo:autoto_int=[](std::string_views)->std::optional<int>{intvalue{};#if __cpp_lib_to_chars >= 202306Lif(std::from_chars(s.data(),s.data()+s.size(),value))#elseif(std::from_chars(s.data(),s.data()+s.size(),value).ec==std::errc{})#endifreturnvalue;elsereturnstd::nullopt;};assert(to_int("42")==42);assert(to_int("foo")==std::nullopt);#if __cpp_lib_constexpr_charconv and __cpp_lib_optional >= 202106static_assert(to_int("42")==42);static_assert(to_int("foo")==std::nullopt);#endif}Output:
String: "1234". Result: 1234, ptr -> "" String: "15 foo". Result: 15, ptr -> " foo" String: "bar". This is not a number. String: " 42". This is not 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
C++17 this function was in
and used
moved to
and uses
C++17 std::from_chars_result might have additional members additional members are prohibited See also
(C++17)
the return type of
(class)
(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
, a file stream or a buffer
(function)
extracts formatted data
(public member function of std::basic_istream<CharT,Traits>)