std::c16rtomb
| Definiert in Header <cuchar> |
||
| std::size_t c16rtomb( char* s, char16_t c16, std::mbstate_t* ps ); |
(seit C++11) | |
Konvertiert einen einzelnen Code-Punkt von einer variablen 16-Bit-Zeichen-Repräsentation (typischerweise UTF-16) in eine schmale Multibyte-Zeichen-Repräsentation.
Wenn s kein Nullzeiger ist und c16 die letzte 16-Bit-Codeeinheit in einer gültigen variablen Kodierung eines Code-Punkts ist, ermittelt die Funktion die Anzahl der Bytes, die zur Speicherung der Multibyte-Zeichen-Repräsentation dieses Code-Punkts benötigt werden (einschließlich aller Shift-Sequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungszustands *ps), und speichert die Multibyte-Zeichen-Repräsentation im Zeichenarray, dessen erstes Element von s gezeigt wird, wobei *ps nach Bedarf aktualisiert wird. Höchstens MB_CUR_MAX Bytes können von dieser Funktion geschrieben werden.
Wenn s ein Nullzeiger ist, ist der Aufruf äquivalent zu std::c16rtomb(buf, u'\0', ps) für einen internen Puffer `buf`.
Wenn c16 nicht die finale Codeeinheit in einer 16-Bit-Repräsentation eines Wide-Characters ist, schreibt die Funktion nicht in das von s gezeigte Array; nur *ps wird aktualisiert.
Wenn c16 das Null-Wide-Character u'\0' ist, wird ein Null-Byte gespeichert, dem jede Shift-Sequenz vorangestellt ist, die notwendig ist, um den initialen Shift-Zustand wiederherzustellen, und der Konvertierungszustandsparameter *ps wird aktualisiert, um den initialen Shift-Zustand darzustellen.
Die von dieser Funktion verwendete Multibyte-Kodierung wird durch die aktuell aktive C-Locale bestimmt.
Inhalt |
[edit] Parameter
| s | - | Zeiger auf das schmale Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird |
| c16 | - | das zu konvertierende 16-Bit-Zeichen |
| ps | - | Zeiger auf das Konvertierungszustandsobjekt, das bei der Interpretation des Multibyte-Strings verwendet wird |
[edit] Rückgabewert
Bei Erfolg gibt die Funktion die Anzahl der Bytes (einschließlich aller Shift-Sequenzen) zurück, die in das Zeichenarray geschrieben wurden, dessen erstes Element von s gezeigt wird. Dieser Wert kann 0 sein, z.B. beim Verarbeiten der ersten char16_t in einem Surrogatpaar.
Bei einem Fehler (wenn c16 kein gültiges 16-Bit-Zeichen ist) gibt die Funktion -1 zurück, speichert EILSEQ in errno und lässt *ps in einem undefinierten Zustand.
[edit] Hinweise
Der C++-Standard verweist für die Semantik dieser Funktion auf den C-Standard. In C11, wie veröffentlicht, kann diese Funktion im Gegensatz zu std::mbrtoc16, das variable Multibyte-Breiten (wie UTF-8) in variable 16-Bit-Breiten (wie UTF-16) konvertiert, nur einzelne 16-Bit-Codeeinheiten konvertieren, was bedeutet, dass es UTF-16 nicht in UTF-8 konvertieren kann, obwohl dies die ursprüngliche Absicht dieser Funktion war. Dies wurde durch den Post-C11-Fehlerbericht DR488 korrigiert.
[edit] Beispiel
Das Beispiel geht davon aus, dass die Korrektur für den Fehlerbericht 488 angewendet wird.
#include <climits> #include <clocale> #include <cuchar> #include <iomanip> #include <iostream> #include <string_view> int main() { std::setlocale(LC_ALL, "en_US.utf8"); std::u16string_view strv = u"zß水🍌"; // or z\u00df\u6c34\U0001F34C std::cout << "Processing " << strv.size() << " UTF-16 code units: [ "; for (char16_t c : strv) std::cout << std::showbase << std::hex << static_cast<int>(c) << ' '; std::cout << "]\n"; std::mbstate_t state{}; char out[MB_LEN_MAX]{}; for (char16_t c : strv) { std::size_t rc = std::c16rtomb(out, c, &state); std::cout << static_cast<int>(c) << " converted to [ "; if (rc != (std::size_t) - 1) for (unsigned char c8 : std::string_view{out, rc}) std::cout << +c8 << ' '; std::cout << "]\n"; } }
Ausgabe
Processing 5 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c ] 0x7a converted to [ 0x7a ] 0xdf converted to [ 0xc3 0x9f ] 0x6c34 converted to [ 0xe6 0xb0 0xb4 ] 0xd83c converted to [ ] 0xdf4c converted to [ 0xf0 0x9f 0x8d 0x8c ]
[edit] Siehe auch
| (C++11) |
konvertiert ein schmales Multibyte-Zeichen in UTF-16-Kodierung (Funktion) |
| (C++20) |
konvertiert einen UTF-8-String in eine schmale Multibyte-Kodierung (Funktion) |
| [virtuell] |
konvertiert eine Zeichenkette von InternT nach ExternT, z. B. beim Schreiben in eine Datei(virtual protected member function of std::codecvt<InternT,ExternT,StateT>) |
| C-Dokumentation für c16rtomb
| |
