Namensräume
Varianten
Aktionen

std::from_chars

Von cppreference.com
< cpp‎ | utility
 
C++
 
Textverarbeitungsbibliothek
 
Definiert in Header <charconv>
std::from_chars_result

    from_chars( const char* first, const char* last,

                /* integer-type */& value, int base = 10 );
 (1) (seit C++17)
(constexpr seit C++23)
std::from_chars_result

    from_chars( const char* first, const char* last,
                /* floating-point-type */& value,

                std::chars_format fmt = std::chars_format::general );
 (2) (seit C++17)

Analysiert die Zeichensequenz [first, last) auf ein unten beschriebenes Muster. Wenn keine Zeichen dem Muster entsprechen oder wenn der Wert, der durch das Parsen der übereinstimmenden Zeichen erhalten wird, nicht im Typ von value darstellbar ist, wird value unverändert gelassen, andernfalls werden die dem Muster entsprechenden Zeichen als Textdarstellung eines arithmetischen Werts interpretiert, der in value gespeichert wird.

1) Integer-Parser: Erwartet das Muster, das identisch mit dem von std::strtol in der Standard-("C")-Locale und der angegebenen von Null verschiedenen numerischen Basis ist, mit der Ausnahme, dass
  • "0x" oder "0X" Präfixe nicht erkannt werden, wenn base 16 ist
  • nur das Minuszeichen erkannt wird (nicht das Pluszeichen), und nur für vorzeichenbehaftete Ganzzahltypen von value
  • führende Leerzeichen nicht ignoriert werden.
Die Bibliothek stellt Überladungen für alle cv-unqualified(seit C++23) vorzeichenbehafteten und vorzeichenlosen Ganzzahltypen und char als Referenztyp des Parameters value bereit.
2) Gleitkomma-Parser: Erwartet das Muster, das identisch mit dem von std::strtod in der Standard-("C")-Locale ist, mit der Ausnahme, dass
In jedem Fall ist der resultierende Wert einer von höchstens zwei Gleitkommawerten, die dem Wert des Strings, der dem Muster entspricht, am nächsten liegen, nach Rundung gemäß std::round_to_nearest.
Die Bibliothek stellt Überladungen für alle cv-unqualified standard(bis C++23) Gleitkommatypen als Referenztyp des Parameters value bereit.

Inhalt

[edit] Parameter

first, last - gültiger Zeichenbereich zum Parsen
value - der Ausgabe-Parameter, in dem der geparste Wert bei Erfolg gespeichert wird
base - zu verwendende Ganzzahlbasis: ein Wert zwischen 2 und 36 (einschließlich).
fmt - zu verwendende Gleitkommaformatierung, eine Bitmaske vom Typ std::chars_format

[edit] Rückgabewert

Bei Erfolg wird ein Wert vom Typ std::from_chars_result zurückgegeben, sodass ptr auf das erste Zeichen zeigt, das nicht dem Muster entspricht, oder den Wert gleich last hat, wenn alle Zeichen übereinstimmen und ec wertinitialisiert ist.

Wenn keine Musterübereinstimmung vorliegt, wird ein Wert vom Typ std::from_chars_result zurückgegeben, sodass ptr gleich first und ec gleich std::errc::invalid_argument ist. value bleibt unverändert.

Wenn das Muster übereinstimmte, aber der geparste Wert nicht im darstellbaren Bereich des Typs von value liegt, wird ein Wert vom Typ std::from_chars_result zurückgegeben, sodass ec gleich std::errc::result_out_of_range und ptr auf das erste Zeichen zeigt, das nicht dem Muster entspricht. value bleibt unverändert.

[edit] Ausnahmen

Wirft nichts.

[edit] Hinweise

Im Gegensatz zu anderen Parsing-Funktionen in C++- und C-Bibliotheken ist std::from_chars lokalitätsunabhängig, allokationsfrei und wirft keine Ausnahmen. Nur eine kleine Teilmenge von Parsing-Richtlinien, die von anderen Bibliotheken verwendet werden (wie z.B. std::sscanf), wird bereitgestellt. Dies soll eine möglichst schnelle Implementierung ermöglichen, die in gängigen Hochdurchsatzkontexten wie textbasiertem Datenaustausch (JSON oder XML) nützlich ist.

Die Garantie, dass std::from_chars jeden durch std::to_chars formatierten Gleitkommawert exakt wiederherstellen kann, ist nur dann gegeben, wenn beide Funktionen von derselben Implementierung stammen.

Ein Muster, das aus einem Vorzeichen ohne nachfolgende Ziffern besteht, wird als ein Muster behandelt, das nichts übereinstimmte.

Feature-Test-Makro Wert Std Feature
__cpp_lib_to_chars 201611L (C++17) Elementare Stringkonvertierungen (std::from_chars, std::to_chars)
202306L (C++26) Testen des Erfolgs oder Misserfolgs von <charconv>-Funktionen
__cpp_lib_constexpr_charconv 202207L (C++23) Fügen Sie constexpr Modifikatoren zu std::from_chars und std::to_chars Überladungen für integrale Typen hinzu

[edit] Beispiel

Führen Sie diesen Code aus
#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
}

Ausgabe

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] Fehlerberichte

Die folgenden Verhaltensändernden Fehlerberichte wurden rückwirkend auf zuvor veröffentlichte C++-Standards angewendet.

DR angewendet auf Verhalten wie veröffentlicht Korrigiertes Verhalten
LWG 2955 C++17 Diese Funktion war in <utility> und verwendete std::error_code verschoben nach <charconv> und verwendet std::errc
LWG 3373 C++17 std::from_chars_result könnte zusätzliche Member haben zusätzliche Member sind verboten

[edit] Siehe auch

(C++17)
 der Rückgabetyp von std::from_chars
(Klasse) [bearbeiten]
(C++17)
 konvertiert einen Ganzzahl- oder Gleitkommawert in eine Zeichensequenz
(Funktion) [bearbeiten]
(C++11)(C++11)(C++11)
 konvertiert einen String in eine vorzeichenbehaftete Ganzzahl
(function) [edit]
(C++11)(C++11)(C++11)
 konvertiert einen String in einen Gleitkommawert
(function) [edit]
(C++11)
 konvertiert einen Byte-String in einen Ganzzahlwert
(Funktion) [bearbeiten]
 konvertiert einen Byte-String in einen Gleitkommawert
(Funktion) [bearbeiten]
 liest formatierte Eingaben von stdin, einem Dateistream oder einem Puffer
(Funktion) [edit]
 extrahiert formatierte Daten
(public member function of std::basic_istream<CharT,Traits>) [edit]
Abgerufen von "https://cppreference.de/mwiki/index.php?title=cpp/utility/from_chars&oldid=179101"