std::from_chars(3)

🌸 std::from_chars — std::from_chars 🌸

ok so this is the page for std::from_chars from the C++ Standard Library — yes bestie, the one that lives in <charconv> and does the parsing thing. Buckle up. 🎀

---

✨ Synopsis ✨

Defined in header <charconv>:

std::from_chars_result
    from_chars( const char* first, const char* last,          (1) (since C++17)
                /* integer-type */& value, int base = 10 );   (constexpr since C++23)

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 );

So what it does: it analyzes the character sequence [first, last) looking for a pattern described down below. If no characters match the pattern, or if the value you get from parsing the matched characters isn't representable in the type of value, then value stays unmodified. Otherwise the characters matching the pattern get interpreted as a text representation of an arithmetic value, and that gets stored in value. 💅

1. Integer parsers: expects the same pattern that std::strtol uses in the default ("C") locale with the given non-zero numeric base — with these exceptions, bestie:
   • "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.

2. Floating-point parsers: expects the same pattern that std::strtod uses in the default ("C") locale — except:
   • 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's 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.

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 gets stored if it's a success
• 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's 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 a value of type std::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 🧚

Throws nothing. literally nothing. icon behaviour. ✨

---

🍓 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's 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. no cap.

A pattern consisting of a sign with no digits following it is treated as a pattern that did not match anything.

Feature-test macros, bestie:

• __cpp_lib_to_chars — 201611L (C++17) — Elementary string conversions (std::from_chars, std::to_chars)
• __cpp_lib_to_chars — 202306L (C++26) — Testing for success or failure of <charconv> functions
• __cpp_lib_constexpr_charconv — 202207L (C++23) — Add constexpr modifiers to 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 retroactively to previously published C++ standards:

• LWG 2955 — applied to C++17 — as published: this function was in <utility> and used std::error_code — corrected: moved to <charconv> and uses std::errc
• LWG 3373 — applied to C++17 — as published: std::from_chars_result might have additional members — corrected: additional members are prohibited

---

💜 See also 💜

• from_chars_result (C++17) — the return type of std::from_chars (class)
• to_chars (C++17) — converts an integer or floating-point value to a character sequence (function)
• stoi, stol, stoll (C++11) — converts a string to a signed integer (function)
• stof, stod, stold (C++11) — converts a string to a floating point value (function)
• strtol, strtoll (C++11) — converts a byte string to an integer value (function)
• strtof, strtod, strtold — converts a byte string to a floating-point value (function)
• scanf, fscanf, sscanf — reads formatted input from stdin, a file stream or a buffer (function); extracts formatted data
• operator>> — public member function of std::basic_istream<CharT,Traits>

---

ok that's the whole page, you ate that 💅 go parse something iconic bestie 🫶

source: cppreference.com — version 2024.06.10 — page: std::from_chars(3) ✨🎀🦋