SysTutorials

Linux Manual Pages › Section 3

stdfrom_chars(3)

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)
                                                                               /*see below*/
                                                                               & value,
                                      int base = 10);
std::from_chars_result from_chars(const char *first, const char *last, float &value, (2)(since C++ 17)
                                                                                         std::chars_format fmt = std::chars_format::general);
std::from_chars_result from_chars(const char *first, const char *last, double &value, (3)(since C++ 17)
                                                                                          std::chars_format fmt = std::chars_format::general);
std::from_chars_result from_chars(const char *first, const char *last, long double &value, (4)(since C++ 17)
                                                                                               std::chars_format fmt = std::chars_format::general);
struct from_chars_result {
    const char *ptr;
    (5)(since C++ 17)
        std::errc ec;
};

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 std::strtol in the default ("C") locale and the given non-zero numeric base, except that
  1. The return type (see Return value below)

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.

Exceptions

(none)

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.

Example

// Run this code

#include <iostream>
#include <charconv>
#include <array>
int main()
{
std::array<char, 10> str{"42"};
int result;
if (auto [p, ec] = std::from_chars(str.data(), str.data() + str.size(), result);
ec == std::errc())
std::cout << result;
}

Output:

  42

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

See also

to_chars converts an integer or floating-point value to a character sequence            (function) (C++17) stoi stol stoll converts a string to a signed integer            (function) (C++11) (C++11) (C++11) stof stod stold converts a string to a floating point value            (function) (C++11) (C++11) (C++11)            converts a byte string to an integer value strtol (function) strtoll 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::basic_istream<CharT,Traits>)