std::from_chars, std::from_chars_result

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) launder (C++17) initializer_list (C++11) source_location (C++20) Three-way comparison (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)    is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20) bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator> rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)    cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17)

 

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,                                    std::chars_format fmt = std::chars_format::general );		(4)	(since C++17)
Helper types
struct from_chars_result {     const char* ptr;     std::errc ec; };		(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.

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 signed and unsigned integer types and char as the referenced type of the parameter value.

2-4) 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_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.

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 std::round_to_nearest.

5) The return type (see Return value below). 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

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 << "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

to_chars (C++17)	converts an integer or floating-point value to a character sequence (function)
stoistolstoll (C++11)(C++11)(C++11)	converts a string to a signed integer (function)
stofstodstold (C++11)(C++11)(C++11)	converts a string to a floating point value (function)
strtolstrtoll (C++11)	converts a byte string to an integer value (function)
strtofstrtodstrtold	converts a byte string to a floating point value (function)
scanffscanfsscanf	reads formatted input from stdin, a file stream or a buffer (function)
operator>>	extracts formatted data (public member function of std::basic_istream<CharT,Traits>)