Namensräume
Varianten
Aktionen

std::codecvt<InternT,ExternT,StateT>::out, do_out

Von cppreference.com
< cpp‎ | locale‎ | codecvt
 
C++
 
Textverarbeitungsbibliothek
 
Lokalisierungsbibliothek
 
std::codecvt
 
Definiert in Header <locale>
public:

result out( StateT& state,
            const InternT* from,
            const InternT* from_end,
            const InternT*& from_next,
            ExternT* to,
            ExternT* to_end,

            ExternT*& to_next ) const;
 (1)
protected:

virtual result do_out( StateT& state,
                       const InternT* from,
                       const InternT* from_end,
                       const InternT*& from_next,
                       ExternT* to,
                       ExternT* to_end,

                       ExternT*& to_next ) const;
 (2)
1) Öffentliche Member-Funktion, ruft die Member-Funktion do_out der am meisten abgeleiteten Klasse auf.
2) Wenn dieses codecvt-Facet eine Konvertierung definiert, übersetzt die internen Zeichen aus dem Quellbereich [from, from_end) in externe Zeichen und platziert die Ergebnisse an den nachfolgenden Stellen beginnend bei to. Konvertiert nicht mehr als from_end - from interne Zeichen und schreibt nicht mehr als to_end - to externe Zeichen. Lässt from_next und to_next auf eines über dem letzten erfolgreich konvertierten Element zeigen.

Wenn dieses codecvt-Facet keine Konvertierung definiert, werden keine Zeichen konvertiert. to_next wird auf to gesetzt, state bleibt unverändert und std::codecvt_base::noconv wird zurückgegeben.

do_out(state, from, from + 1, from_next, to, to_end, to_next) muss ok zurückgeben, wenn

  • dieses codecvt-Facet von basic_filebuf verwendet wird, und
  • do_out(state, from, from_end, from_next, to, to_end, to_next) ok zurückgeben würde, wobei from != from_end gilt.

Inhalt

[bearbeiten] Rückgabewert

Ein Wert vom Typ std::codecvt_base::result, der den folgenden Erfolgstatus angibt:

ok Konvertierung abgeschlossen
partiell Nicht genügend Speicher im Ausgabepuffer oder unerwartetes Ende des Quellpuffers
error Ein Zeichen getroffen, das nicht konvertiert werden konnte
noconv Dieses Facet ist nicht konvertierend, keine Ausgabe geschrieben

Die nicht-konvertierende Spezialisierung std::codecvt<char, char, std::mbstate_t> gibt immer std::codecvt_base::noconv zurück.

[bearbeiten] Hinweise

Erfordert, dass from <= from_end && to <= to_end und dass state entweder den initialen Umschaltzusstand repräsentiert oder durch Konvertierung der vorhergehenden Zeichen der Sequenz erhalten wurde.

Während codecvt N:M-Konvertierungen unterstützt (z. B. UTF-16 nach UTF-8, wobei zwei interne Zeichen notwendig sein können, um zu entscheiden, welche externen Zeichen ausgegeben werden sollen), können std::basic_filebuf nur codecvt-Facetten verwenden, die eine 1:N-Konvertierung definieren, d.h. sie muss in der Lage sein, ein internes Zeichen nach dem anderen beim Schreiben in eine Datei zu verarbeiten.

Bei N:M-Konvertierungen kann diese Funktion std::codecvt_base::partial zurückgeben, nachdem alle Quellzeichen verbraucht wurden (from_next == from_end). Das bedeutet, dass ein weiteres internes Zeichen zur Vervollständigung der Konvertierung benötigt wird (z.B. beim Konvertieren von UTF-16 nach UTF-8, wenn das letzte Zeichen im Quellpuffer ein hoher Surrogat ist).

Die Auswirkung auf state ist bewusst nicht spezifiziert. In Standard-Facetten wird es verwendet, um den Umschaltzusstand zu pflegen, wie beim Aufruf von std::wcsrtombs, und wird daher aktualisiert, um den Umschaltzusstand nach dem letzten erfolgreich konvertierten Zeichen widerzuspiegeln. Ein benutzerdefiniertes Facet ist jedoch frei, es zu verwenden, um jeden anderen Zustand zu pflegen, z.B. die Anzahl der speziellen Zeichen zu zählen, auf die gestoßen wurde.

[bearbeiten] Beispiel

Führen Sie diesen Code aus
#include <iostream>
#include <locale>
#include <string>
 
int main()
{
    std::locale::global(std::locale("en_US.utf8"));
    auto& f = std::use_facet<std::codecvt<wchar_t, char, std::mbstate_t>>(std::locale());
    std::wstring internal = L"z\u00df\u6c34\U0001f34c"; // L"zß水🍌"
 
    // note that the following can be done with wstring_convert
    std::mbstate_t mb{}; // initial shift state
    std::string external(internal.size() * f.max_length(), '\0'); 
    const wchar_t* from_next;
    char* to_next;
    f.out(mb, &internal[0], &internal[internal.size()], from_next,
              &external[0], &external[external.size()], to_next);
    // error checking skipped for brevity
    external.resize(to_next - &external[0]);
 
    std::cout << "The string in narrow multibyte encoding: " << external << '\n';
}

Ausgabe

The string in narrow multibyte encoding: zß水🍌

[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 76 C++98 Es war unklar, ob die Konvertierung erforderlich war
um die Verarbeitung eines internen Zeichens auf einmal zu unterstützen		 nur erforderlich, wenn verwendet
von basic_filebuf

[bearbeiten] Siehe auch

[virtuell]
 schreibt Zeichen aus dem Schreibbereich in die zugeordnete Datei
(virtuelle geschützte Memberfunktion von std::basic_filebuf<CharT,Traits>) [bearbeiten]
 konvertiert einen Wide-String in einen Byte-String
(öffentliche Member-Funktion von std::wstring_convert<Codecvt,Elem,Wide_alloc,Byte_alloc>) [bearbeiten]
 konvertiert einen Wide-String in einen schmalen Multibyte-Zeichenstring, gegeben den Zustand
(Funktion) [bearbeiten]
[virtuell]
 konvertiert eine Zeichenkette von ExternT nach InternT, z. B. beim Lesen aus einer Datei
(virtual protected member function) [bearbeiten]
Abgerufen von "https://cppreference.de/mwiki/index.php?title=cpp/locale/codecvt/out&oldid=160052"