mbrtoc16, mbrtoc32

  • Artikel

Übersetzt das erste UTF-8-Multibytezeichen in einer Zeichenfolge in das entsprechende UTF-16- oder UTF-32-Zeichen.

Syntax

size_t mbrtoc16(
   char16_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

size_t mbrtoc32(
   char32_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

Parameter

destination
Zeiger auf die char16_t- oder char32_t-Entsprechung des zu konvertierenden UTF-8-Multibytezeichens. Wenn der Wert NULL ist, speichert die Funktion keinen Wert.

source
Zeiger auf die zu konvertierende UTF-8-Multibyte-Zeichenfolge.

max_bytes
Die maximale Anzahl Bytes in source , die für ein zu konvertierendes Zeichen untersucht werden sollen. Dieses Argument sollte ein Wert zwischen einem und der Anzahl der Bytes sein, einschließlich eines null-Endators, der in source.

state
Zeiger auf ein mbstate_t Konvertierungsstatusobjekt, mit dem die UTF-8-Multibyte-Zeichenfolge in ein oder mehrere Ausgabezeichen interpretiert wird.

Rückgabewert

Im Erfolgsfall wird der Wert der ersten erfüllten Bedingung zurückgegeben, auf der Grundlage des aktuellen state -Werts:

Wert Bedingung
0 Die nächsten max_bytes oder weniger Zeichen, die konvertiert werden source , entsprechen dem nullweiten Zeichen, bei dem es sich um den gespeicherten Wert handelt, wenn destination er nicht null ist.

state enthält den UMSCHALT-Status zu Anfang.
Zwischen 1 und max_byteseinschließlich Der zurückgegebene Wert ist die Anzahl Bytes von source , die ein gültiges Multibytezeichen bilden. Das konvertierte breite Zeichen wird gespeichert, wenn destination es nicht NULL ist.
3- Das nächste breite Zeichen, das sich aus einem vorherigen Aufruf der Funktion ergibt, wurde gespeichert destination , wenn destination er nicht NULL ist. Keine Bytes von source werden von diesem Aufruf der Funktion verbraucht.

Wenn source auf ein UTF-8-Multibyte-Zeichen zeigt, das mehr als ein breites Zeichen darstellen muss (z. B. ein Ersatzpaar), wird der state Wert aktualisiert, sodass der nächste Funktionsaufruf das zusätzliche Zeichen ausschreibt.
-2 Die nächsten max_bytes Bytes stellen ein unvollständiges, aber potenziell gültiges UTF-8-Zeichen dar. Es wird kein Wert in destinationgespeichert. Dieses Ergebnis kann auftreten, wenn max_bytes 0 (null) ist.
-1 Es ist ein Codierungsfehler aufgetreten. Die nächsten max_bytes oder weniger Bytes tragen nicht zu einem vollständigen und gültigen UTF-8-Multibyte-Zeichen bei. Es wird kein Wert in destinationgespeichert.

EILSEQ wird gespeichert errno , und der Konvertierungszustandswert state ist nicht angegeben.

Hinweise

Die mbrtoc16 Funktion liest bis zu max_bytes Byte aus source , um das erste vollständige, gültige UTF-8-Multibyte-Zeichen zu finden, und speichert dann das entsprechende UTF-16-Zeichen in destination. Wenn für das Zeichen mehr als ein UTF-16-Ausgabezeichen erforderlich ist, z. B. ein Ersatzpaar, wird der state Wert so festgelegt, dass das nächste UTF-16-Zeichen destination im nächsten Aufruf von mbrtoc16 Die mbrtoc32 -Funktion ist identisch, jedoch wird die Ausgabe als UTF-32-Zeichen gespeichert.

Wenn source null ist, geben diese Funktionen das Äquivalent eines Aufrufs zurück, der mithilfe von Argumenten für NULL destination, "" (eine leere, null-beendete Zeichenfolge) für sourceund 1 für max_bytes. Die übergebenen Werte von destination und max_bytes werden ignoriert.

Ist source dies nicht null, beginnt die Funktion am Anfang der Zeichenfolge und überprüft bis zu max_bytes Bytes, um die Anzahl der Bytes zu ermitteln, die erforderlich sind, um das nächste UTF-8-Multibyte-Zeichen einschließlich aller Schichtabfolgen abzuschließen. Wenn die untersuchten Bytes ein gültiges und vollständiges UTF-8-Multibytezeichen enthalten, konvertiert die Funktion das Zeichen in das bzw. die entsprechende(n) 16-Bit- oder 32-Bit-Breitzeichen. Ist destination dies nicht null, speichert die Funktion das erste (und möglicherweise nur) Ergebniszeichen im Ziel. Wenn zusätzliche Ausgabezeichen erforderlich sind, wird ein Wert festgelegt state, sodass nachfolgende Aufrufe der Funktion die zusätzlichen Zeichen ausgeben und den Wert -3 zurückgeben. Wenn keine weiteren Ausgabezeichen erforderlich sind, wird state auf den ursprünglichen Umschaltzustand zurückgesetzt.

Um Nicht-UTF-8-Multibyte-Zeichen in UTF-16 LE-Zeichen zu konvertieren, verwenden Sie die mbrtowcFunktionen mbtowc oder _mbtowc_l .

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Anforderungen

Funktion C-Header C++-Header
mbrtoc16, mbrtoc32 <uchar.h> <cuchar>

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s