Namespaces
Variants

std:: to_chars

From cppreference.net
C++
Text processing library
Definiert im 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)

Wandelt value durch sukzessives Füllen des Bereichs [ first , last ) in eine Zeichenkette um, wobei [ first , last ) ein gültiger Bereich sein muss.

1) Ganzzahlformatierer: value wird in eine Ziffernfolge zur angegebenen base umgewandelt (ohne überflüssige führende Nullen). Ziffern im Bereich 10..35 (inklusive) werden als Kleinbuchstaben a..z dargestellt. Wenn value kleiner als null ist, beginnt die Darstellung mit einem Minuszeichen. Die Bibliothek stellt Überladungen für alle cv-unqualifizierten 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" und nicht "false" / "true" wäre, wenn es erlaubt wäre.
3) value wird in einen String im Stil von std::printf in der Standard-("C")-Locale konvertiert. Der Konvertierungsspezifizierer ist f oder e (mit Bevorzugung von f bei Gleichstand), gewählt entsprechend der Anforderung einer kürzesten Darstellung: Die String-Darstellung besteht aus der kleinsten Anzahl von Zeichen, sodass mindestens eine Ziffer vor dem Dezimalpunkt (falls vorhanden) steht und das Parsen der Darstellung unter Verwendung der entsprechenden std::from_chars -Funktion den Wert exakt wiederherstellt. Wenn es mehrere solcher Darstellungen gibt, wird diejenige mit der kleinsten Differenz zu value gewählt, wobei verbleibende Gleichstände durch Rundung gemäß std::round_to_nearest aufgelöst werden. Die Bibliothek bietet Überladungen für alle cv-unqualifizierten Standard (bis C++23) Gleitkommatypen als Typ des Parameters value an.
4) Gleich wie (3) , aber die für die as-if printf spezifizierte Konvertierung ist f falls fmt gleich std::chars_format::fixed ist, e falls fmt gleich std::chars_format::scientific ist, a (aber ohne führendes "0x" im Ergebnis) falls fmt gleich std::chars_format::hex ist, und g falls fmt gleich chars_format::general ist. Die Bibliothek stellt Überladungen für alle cv-unqualifizierten Standard (bis C++23) Gleitkommatypen als Typ des Parameters value bereit.
5) Gleich wie (4) , außer dass die Genauigkeit durch den Parameter precision festgelegt wird, anstatt durch die Anforderung der kürzesten Darstellung. Die Bibliothek bietet Überladungen für alle cv-unqualifizierten Standard (bis C++23) Gleitkommatypen als Typ des Parameters value an.

Inhaltsverzeichnis

Parameter

first, last - Zeichenbereich, in den geschrieben werden soll
value - der Wert, der in seine Zeichenkettenrepräsentation umgewandelt werden soll
base - zu verwendende Ganzzahlbasis: ein Wert zwischen 2 und 36 (einschließlich).
fmt - zu verwendende Gleitkommaformatierung, eine Bitmaske vom Typ std::chars_format
precision - zu verwendende Gleitkommagenauigkeit

Rückgabewert

Bei Erfolg gibt einen Wert vom Typ std::to_chars_result zurück, sodass ec einem wertinitialisierten std::errc entspricht und ptr den Zeiger auf das Ende der geschriebenen Zeichen darstellt. Beachten Sie, dass die Zeichenkette nicht NUL-terminiert ist.

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

Ausnahmen

Wirft nichts.

Hinweise

Im Gegensatz zu anderen Formatierungsfunktionen in C++- und C-Bibliotheken ist std::to_chars gebietsschemaineutral, nicht-allozierend und nicht-werfend. Nur ein kleiner Teil der von anderen Bibliotheken verwendeten Formatierungsrichtlinien (wie std::sprintf ) wird bereitgestellt. Dies soll die schnellstmögliche Implementierung ermöglichen, die in gängigen Hochdurchsatz-Szenarien nützlich ist, wie z.B. textbasierter Austausch ( JSON oder XML ).

Die Garantie, dass std::from_chars jeden von std::to_chars formatierten Gleitkommawert exakt wiederherstellen kann, gilt nur, wenn beide Funktionen aus derselben Implementierung stammen.

Um einen bool -Wert als "0" / "1" mit std::to_chars zu formatieren, muss der Wert in einen anderen Integer-Typ umgewandelt werden.

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 auf Erfolg oder Misserfolg von <charconv> Funktionen
__cpp_lib_constexpr_charconv 202207L (C++23) Hinzufügen von constexpr Modifikatoren zu std::to_chars und std::from_chars Überladungen ( 1 ) für integrale Typen

Beispiel

Diesen Code ausführen 
#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

Fehlerberichte

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

DR Angewendet auf Verhalten wie veröffentlicht Korrektes 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 bool Argument wurde akzeptiert und zu int heraufgestuft durch eine gelöschte Überladung abgelehnt
LWG 3373 C++17 std::to_chars_result könnte zusätzliche Member haben zusätzliche Member sind nicht erlaubt

Siehe auch

(C++17)
der Rückgabetyp von std::to_chars
(Klasse)
(C++17)
konvertiert eine Zeichenfolge in einen Ganzzahl- oder Gleitkommawert
(Funktion)
(C++11)
konvertiert einen Ganzzahl- oder Gleitkommawert in string
(Funktion)
(C++11)
gibt formatierte Ausgabe auf stdout , einen Dateistrom oder einen Puffer aus
(Funktion)
fügt formatierte Daten ein
(öffentliche Elementfunktion von std::basic_ostream<CharT,Traits> )