Namensräume
Varianten
Aktionen

std::to_chars

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

    to_chars( char* first, char* last,

              /* integer-type */ value, int base = 10 );
 (1) (seit C++17)
(constexpr seit C++23)
std::to_chars_result
    to_chars( char*, char*, bool, int = 10 ) = delete;
 (2) (seit C++17)
std::to_chars_result
    to_chars( char* first, char* last, /* floating-point-type */ value );
 (3) (seit C++17)
std::to_chars_result

    to_chars( char* first, char* last, /* floating-point-type */ value,

              std::chars_format fmt );
 (4) (seit C++17)
std::to_chars_result

    to_chars( char* first, char* last, /* floating-point-type */ value,

              std::chars_format fmt, int precision );
 (5) (seit C++17)

Konvertiert value in einen Zeichenstring, indem der Bereich [first, last) sukzessive gefüllt wird, wobei [first, last) ein gültiger Bereich sein muss.

1) Integer-Formatierer: value wird in einen String von Ziffern in der angegebenen base (ohne redundante führende Nullen) konvertiert. Ziffern im Bereich 10..35 (inklusive) werden als Kleinbuchstaben a..z dargestellt. Wenn value negativ ist, beginnt die Darstellung mit einem Minuszeichen. Die Bibliothek stellt Überladungen für alle cv-unqualified(seit C++23) vorzeichenbehafteten und vorzeichenlosen Ganzzahltypen sowie für den Typ char als Typ des Parameters value bereit.
2) Überladung für bool ist gelöscht. std::to_chars lehnt Argumente vom Typ bool ab, da das Ergebnis "0"/"1" wäre, aber nicht "false"/"true", wenn es erlaubt wäre.
3) value wird in einen String konvertiert, als ob std::printf in der Standard("C")-Locale verwendet würde. Der Konversionsspezifizierer ist f oder e (bei Gleichstand wird f bevorzugt), gewählt nach der Anforderung einer kürzestmöglichen Darstellung: Die String-Darstellung besteht aus der kleinstmöglichen Anzahl von Zeichen, sodass mindestens eine Ziffer vor dem Dezimaltrennzeichen (falls vorhanden) steht und das Parsen der Darstellung mit der entsprechenden std::from_chars-Funktion den Wert exakt wiederherstellt. Wenn es mehrere solche Darstellungen gibt, wird eine mit der geringsten Differenz zu value gewählt, wobei verbleibende Gleichstände durch Rundung gemäß std::round_to_nearest aufgelöst werden. Die Bibliothek stellt Überladungen für alle cv-unqualified standard(bis C++23) Gleitkommatypen als Typ des Parameters value bereit.
4) Ähnlich wie in (3), aber die Konversion, die für das "as-if printf" angegeben ist, ist f, wenn fmt std::chars_format::fixed ist, e, wenn fmt std::chars_format::scientific ist, a (aber ohne führendes "0x" im Ergebnis), wenn fmt std::chars_format::hex ist, und g, wenn fmt chars_format::general ist. Die Bibliothek stellt Überladungen für alle cv-unqualified standard(bis C++23) Gleitkommatypen als Typ des Parameters value bereit.
5) Ähnlich wie in (4), außer dass die Genauigkeit durch den Parameter precision anstelle der Anforderung der kürzesten Darstellung angegeben wird. Die Bibliothek stellt Überladungen für alle cv-unqualified standard(bis C++23) Gleitkommatypen als Typ des Parameters value bereit.

Inhalt

[bearbeiten] Parameter

first, last - Zeichenbereich, in den geschrieben werden soll
value - der Wert, der in seine String-Darstellung konvertiert werden soll
base - zu verwendende Integer-Basis: ein Wert zwischen 2 und 36 (inklusive).
fmt - zu verwendende Gleitkommaformatierung, eine Bitmaske vom Typ std::chars_format
precision - zu verwendende Gleitkomma-Genauigkeit

[bearbeiten] Rückgabewert

Im Erfolgsfall wird ein Wert vom Typ std::to_chars_result zurückgegeben, bei dem ec gleich dem wertinitialisierten std::errc ist und ptr der Zeiger auf das Ende des geschriebenen Zeichens ist. Beachten Sie, dass der String *nicht* NUL-terminiert ist.

Im Fehlerfall wird ein Wert vom Typ std::to_chars_result zurückgegeben, der std::errc::value_too_large in ec enthält, eine Kopie des Wertes last in ptr, und lässt den Inhalt des Bereichs [first, last) in einem undefinierten Zustand.

[bearbeiten] Ausnahmen

Wirft nichts.

[bearbeiten] Hinweise

Im Gegensatz zu anderen Formatierungsfunktionen in C++- und C-Bibliotheken ist std::to_chars locale-unabhängig, allokationsfrei und wirft keine Ausnahmen. Es wird nur ein kleiner Teil der Formatierungsrichtlinien bereitgestellt, die von anderen Bibliotheken (wie std::sprintf) verwendet werden. 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 von std::to_chars formatierten Gleitkommawert exakt wiederherstellen kann, wird nur dann gegeben, wenn beide Funktionen von derselben Implementierung stammen.

Es ist erforderlich, einen bool-Wert explizit in einen anderen Ganzzahltyp umzuwandeln, wenn der Wert als "0"/"1" formatiert werden soll.

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

[bearbeiten] Beispiel

Führen Sie diesen Code aus
#include <charconv>
#include <iomanip>
#include <iostream>
#include <string_view>
#include <system_error>
 
void show_to_chars(auto... format_args)
{
    const size_t buf_size = 10;
    char buf[buf_size]{};
    std::to_chars_result result = std::to_chars(buf, buf + buf_size, format_args...);
 
    if (result.ec != std::errc())
        std::cout << std::make_error_code(result.ec).message() << '\n';
    else
    {
        std::string_view str(buf, result.ptr - buf);
        std::cout << std::quoted(str) << '\n';
    }
}
 
int main()
{
    show_to_chars(42);
    show_to_chars(+3.14159F);
    show_to_chars(-3.14159, std::chars_format::fixed);
    show_to_chars(-3.14159, std::chars_format::scientific, 3);
    show_to_chars(3.1415926535, std::chars_format::fixed, 10);
}

Mögliche Ausgabe

"42"
"3.14159"
"-3.14159"
"-3.142e+00"
Value too large for defined data type

[bearbeiten] 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 3266 C++17 Das Argument bool wurde akzeptiert und zu int hochgestuft abgelehnt durch eine gelöschte Überladung
LWG 3373 C++17 std::to_chars_result könnte zusätzliche Member haben zusätzliche Member sind nicht zulässig

[bearbeiten] Siehe auch

(C++17)
 der Rückgabetyp von std::to_chars
(Klasse) [bearbeiten]
(C++17)
 konvertiert eine Zeichensequenz in einen Ganzzahl- oder Gleitkommawert
(Funktion) [bearbeiten]
(C++11)
 konvertiert einen ganzzahligen oder Gleitkommawert in einen string
(function) [edit]
(C++11)
 druckt formatierte Ausgabe nach stdout, einen Dateistream oder einen Puffer
(Funktion) [bearbeiten]
 fügt formatierte Daten ein
(public member function of std::basic_ostream<CharT,Traits>) [bearbeiten]
Abgerufen von "https://cppreference.de/mwiki/index.php?title=cpp/utility/to_chars&oldid=179100"