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 ofvalue,value is unmodified, otherwise the characters matching the pattern are interpreted as a text representation of an arithmetic value, which is stored invalue.

[edit]Parameters

[edit]Return value

On success, returns a value of typestd::from_chars_result such thatptr points at the first character not matching the pattern, or has the value equal tolast if all characters match andec is value-initialized.

If there is no pattern match, returns a value of typestd::from_chars_result such thatptr equalsfirst andec equalsstd::errc::invalid_argument.value is unmodified.

If the pattern was matched, but the parsed value is not in the range representable by the type ofvalue, returns value of typestd::from_chars_result such thatec equalsstd::errc::result_out_of_range andptr points at the first character not matching the pattern.value is unmodified.

[edit]Exceptions

Throws nothing.

[edit]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 asstd::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 orXML).

The guarantee thatstd::from_chars can recover every floating-point value formatted bystd::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.

[edit]Example

#include <cassert>#include <charconv>#include <iomanip>#include <iostream>#include <optional>#include <string_view>#include <system_error> int main(){for(std::string_viewconst 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';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:auto to_int=[](std::string_view s)->std::optional<int>{int value{};#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{})#endifreturn value;elsereturnstd::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}

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.

[edit]Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit]See also

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文