c32rtomb
| Definiert im Header <uchar.h> |
||
| (seit C11) | ||
Konvertiert einen einzelnen Codepunkt von seiner variablen 32-Bit-Breitzeichen-Darstellung (typischerweise UTF-32) in seine schmale Multibyte-Zeichen-Darstellung.
Wenn s kein Nullzeiger ist, ermittelt die Funktion die Anzahl der Bytes, die zur Speicherung der Multibyte-Zeichen-Darstellung von c32 erforderlich sind (einschließlich etwaiger Umschaltsequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungsstatus *ps), und speichert die Multibyte-Zeichen-Darstellung im Zeichenarray, dessen erstes Element von s gezeigt wird, wobei *ps bei Bedarf aktualisiert wird. Maximal MB_CUR_MAX Bytes können von dieser Funktion geschrieben werden.
Wenn s ein Nullzeiger ist, ist der Aufruf äquivalent zu c32rtomb(buf, U'\0', ps) für einen internen Puffer buf.
Wenn c32 das Null-Breitzeichen U'\0' ist, wird ein Null-Byte gespeichert, dem eine Umschaltsequenz vorangestellt ist, die erforderlich ist, um den ursprünglichen Umschaltzustand wiederherzustellen, und der Konvertierungsstatusparameter *ps wird aktualisiert, um den ursprünglichen Umschaltzustand darzustellen.
Wenn das Makro __STDC_UTF_32__ definiert ist, ist die von dieser Funktion verwendete 32-Bit-Kodierung UTF-32; andernfalls ist sie implementierungsabhängig. Das Makro ist immer definiert und die Kodierung ist immer UTF-32.(seit C23) In jedem Fall wird die von dieser Funktion verwendete Multibyte-Zeichenkodierung durch die aktuell aktive C-Locale bestimmt.
Inhalt |
[edit] Parameter
| s | - | Zeiger auf das schmale Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird |
| c32 | - | das zu konvertierende 32-Bit-Breitzeichen |
| ps | - | Zeiger auf das Konvertierungszustandsobjekt, das bei der Interpretation des Multibyte-Strings verwendet wird |
[edit] Rückgabewert
Bei Erfolg wird die Anzahl der Bytes (einschließlich etwaiger Umschaltsequenzen) zurückgegeben, die in das Zeichenarray geschrieben wurden, dessen erstes Element von s gezeigt wird. Dieser Wert kann 0 sein, z. B. bei der Verarbeitung der führenden char32_t-Einheiten in einer Multi-char32_t-Einheiten-Sequenz (tritt in UTF-32 nicht auf).
Bei einem Fehler (wenn c32 kein gültiges 32-Bit-Breitzeichen ist) wird -1 zurückgegeben, EILSEQ wird in errno gespeichert und *ps verbleibt in einem undefinierten Zustand.
[edit] Beispiel
Unter MSVC benötigen Sie das Compiler-Flag /utf-8, damit UTF_8 korrekt funktioniert.
#include <locale.h> #include <stdio.h> #include <stdlib.h> #include <uchar.h> int main(void) { setlocale(LC_ALL, "en_US.utf8"); const char32_t in[] = U"zß水🍌"; // or "z\u00df\u6c34\U0001F34C" size_t in_sz = sizeof in / sizeof *in; printf("Processing %zu UTF-32 code units: [", in_sz); for (size_t n = 0; n < in_sz; ++n) printf("%s%08X", n ? " " : "", in[n]); puts("]"); char* out = malloc(MB_CUR_MAX * in_sz); char* p = out; mbstate_t state = {0}; for (size_t n = 0; n < in_sz; ++n) { size_t rc = c32rtomb(p, in[n], &state); if(rc == (size_t)-1) break; p += rc; } size_t out_sz = p - out; printf("into %zu UTF-8 code units: [", out_sz); for (size_t x = 0; x < out_sz; ++x) printf("%s%02X", x ? " " : "", +(unsigned char)out[x]); puts("]"); free(out); }
Ausgabe
Processing 5 UTF-32 code units: [0000007A 000000DF 00006C34 0001F34C 00000000] into 11 UTF-8 code units: [7A C3 9F E6 B0 B4 F0 9F 8D 8C 00]
[edit] Referenzen
- C23-Standard (ISO/IEC 9899:2024)
- 7.30.1.6 Die Funktion c32rtomb (S. 411)
- C11-Standard (ISO/IEC 9899:2011)
- 7.28.1.4 Die Funktion c32rtomb (S. 401)
[edit] Siehe auch
| (C11) |
konvertiert ein schmales Multibyte-Zeichen in UTF-32-Kodierung (Funktion) |
| C++ Dokumentation für c32rtomb
| |
