std::from_chars(3) C++ Standard Libary std::from_chars(3) NAME std::from_chars - std::from_chars Synopsis Defined in header <charconv> std::from_chars_result from_chars( const char* first, const char* last, (1) (since C++17) (constexpr since C++23) /* integer-type */& value, int base = 10 ); std::from_chars_result from_chars( const char* first, const char* last, /* floating-point-type */& value, (2) (since C++17) std::chars_format fmt = std::chars_format::general ); 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 unmodi- fied, otherwise the characters matching the pattern are interpreted as a text represen- tation of an arithmetic value, which is stored in value. 1) Integer parsers: Expects the pattern identical to the one used by std::strtol 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 refer- enced type of the parameter value. 2) 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 has std::chars_format::scientific set but not std::chars_for- mat::fixed, the exponent part is required (otherwise it is optional) * if fmt has std::chars_format::fixed set but not std::chars_for- mat::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. 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 accord- ing to std::round_to_nearest. The library provides overloads for all cv-unqualified standard (until C++23) floating-point types as the referenced type of the parame- ter value. Parameters first, last - valid character range to parse value - the out-parameter where the parsed value is stored if suc- cessful 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 std::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 std::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 std::from_chars_result such that ec equals std::errc::result_out_of_range and ptr points at the first char- acter 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 sub- set 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 Value Std Feature 201611L (C++17) Elementary string conver- sions __cpp_lib_to_chars (std::from_chars, std::to_chars) 202306L (C++26) Testing for success or failure of <charconv> functions Add constexpr modifiers to __cpp_lib_constexpr_charconv 202207L (C++23) std::from_chars and std::to_chars overloads for integral types Example // Run this code #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 << "This is not 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 / C++26's operator bool() demo: auto to_int = [](std::string_view s) -> std::optional<int> { int value{}; #if __cpp_lib_to_chars >= 202306L if (std::from_chars(s.data(), s.data() + s.size(), value)) #else if (std::from_chars(s.data(), s.data() + s.size(), value).ec == std::errc{}) #endif 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 } 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 retroac- tively to previously published C++ standards. DR Applied to Behavior as published Correct behavior LWG 2955 C++17 this function was in <utility> and used moved to <charconv> and std::error_code uses std::errc LWG 3373 C++17 std::from_chars_result might have additional members are additional members prohibited See also from_chars_result the return type of std::from_chars (C++17) (class) to_chars converts an integer or floating-point value to a char- acter (C++17) sequence (function) stoi stol stoll converts a string to a signed integer (C++11) (function) (C++11) (C++11) stof stod stold converts a string to a floating point value (C++11) (function) (C++11) (C++11) strtol converts a byte string to an integer value strtoll (function) (C++11) strtof converts a byte string to a floating-point value strtod (function) strtold scanf reads formatted input from stdin, a file stream or a buffer fscanf (function) sscanf extracts formatted data operator>> (public member function of std::ba- sic_istream<CharT,Traits>) http://cppreference.com 2024.06.10 std::from_chars(3)
NAME | Synopsis | Parameters | Return value | Exceptions | Notes | Example | Output: | See also
Want to link to this manual page? Use this URL:
<https://man.FreeBSD.org/cgi/man.cgi?query=std::from_chars&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>