wctomb, wctomb_s

 

C

Compiler-Unterstützung

Sprache

Header

Typunterstützung

Programm-Dienstprogramme

Unterstützung für variable Funktionsargumente

Fehlerbehandlung

Dynamische Speicherverwaltung

Bibliothek für Zeichenketten

Algorithmen

Numerik

Datums- und Zeitdienstprogramme

Ein-/Ausgabeunterstützung

Lokalisierungsunterstützung

Unterstützung für Nebenläufigkeit (C11)

Technische Spezifikationen

Symbolindex

 

Bibliothek für Zeichenketten

Null-terminierte Byte-Strings

Null-terminierte Multibyte-Strings

Null-terminierte breite Zeichenketten

 

Null-terminierte Multibyte-Strings

Funktionen
Breit-/Multibyte-Konvertierungen
mbsinit (C95)
mbstowcsmbstowcs_s (C11) btowc (C95) mbrtowc (C95) mbsrtowcsmbsrtowcs_s (C95)(C11)   mbrtoc8 (C23) c8rtomb (C23) mbrtoc16 (C11) c16rtomb (C11) c32rtomb (C11) mbrtoc32 (C11)	mblen mbtowc wctombwctomb_s (C11) wcstombswcstombs_s (C11) wctob (C95) wcrtombwcrtomb_s (C95)(C11) wcsrtombswcsrtombs_s (C95)(C11) mbrlen (C95)
Typen
mbstate_t (C95) char8_t (C23)	char16_t (C11) char32_t (C11)
Makros
MB_LEN_MAX	MB_CUR_MAX

 

Definiert im Header <stdlib.h>
int wctomb( char *s, wchar_t wc );	(1)
errno_t wctomb_s( int *restrict status, char *restrict s, rsize_t ssz, wchar_t wc );	(2)	(seit C11)

1) Wandelt ein Wide-Zeichen wc in die Multibyte-Kodierung um und speichert es (einschließlich aller Sequenzen) im Zeichenarray, dessen erstes Element von s gezeigt wird. Es werden nicht mehr als MB_CUR_MAX Zeichen gespeichert. Die Konvertierung wird von der LC_CTYPE-Kategorie der aktuellen Locale beeinflusst.

Wenn wc das Nullzeichen ist, wird das Nullbyte in s geschrieben, vorangestellt von allen notwendigen Sequenzen, um den initialen Shift-Status wiederherzustellen.

Wenn s ein Nullzeiger ist, setzt diese Funktion den globalen Konvertierungsstatus zurück und ermittelt, ob Sequenzen verwendet werden.

2) Wie (1), außer dass das Ergebnis im Ausgabeparameter status zurückgegeben wird und die folgenden Fehler zur Laufzeit erkannt und die aktuell installierte Constraint-Handler-Funktion aufrufen.

• ssz ist kleiner als die Anzahl der Bytes, die geschrieben würden (es sei denn, s ist null)
• ssz ist größer als RSIZE_MAX (es sei denn, s ist null)
• s ist ein Nullzeiger, aber ssz ist nicht null

Wie bei allen bounds-checked Funktionen ist wctomb_s nur garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ vor dem Einbinden von <stdlib.h> auf die ganzzahlige Konstante 1 definiert.

Hinweise

Jeder Aufruf von wctomb aktualisiert den internen globalen Konvertierungsstatus (ein statisches Objekt vom Typ mbstate_t, das nur dieser Funktion bekannt ist). Wenn die Multibyte-Kodierung Shift-Status verwendet, ist diese Funktion nicht reentrant. In jedem Fall sollten mehrere Threads wctomb nicht ohne Synchronisation aufrufen: stattdessen können wcrtomb oder wctomb_s verwendet werden.

Im Gegensatz zu den meisten bounds-checked Funktionen terminiert wctomb_s ihre Ausgabe nicht null, da sie für die Verwendung in Schleifen konzipiert ist, die Zeichenketten Zeichen für Zeichen verarbeiten.

Parameter

s	-	Zeiger auf das Zeichenarray für die Ausgabe
wc	-	Wide-Zeichen, das konvertiert werden soll
ssz	-	maximale Anzahl von Bytes, die in s geschrieben werden sollen (Größe des Arrays s)
status	-	Zeiger auf einen Ausgabeparameter, in dem das Ergebnis (Länge der Multibyte-Sequenz oder der Status der Sequenz) gespeichert wird

Rückgabewert

1) Wenn s kein Nullzeiger ist, gibt die Anzahl der Bytes zurück, die in der Multibyte-Darstellung von wc enthalten sind, oder -1, wenn wc kein gültiges Zeichen ist.

Wenn s ein Nullzeiger ist, wird sein interner Konvertierungsstatus auf den initialen Shift-Status zurückgesetzt und gibt ​0​ zurück, wenn die aktuelle Multibyte-Kodierung nicht zustandsabhängig ist (keine Shift-Sequenzen verwendet), oder einen Wert ungleich Null, wenn die aktuelle Multibyte-Kodierung zustandsabhängig ist (Shift-Sequenzen verwendet).

2) null im Erfolgsfall, wobei die Multibyte-Darstellung von wc in s gespeichert wird und ihre Länge in *status gespeichert wird, oder, wenn s null ist, wird der Status der Shift-Sequenz in status gespeichert). Ungleich null bei Kodierungsfehler oder Laufzeit-Constraint-Verletzung, wobei (size_t)-1 in *status gespeichert wird. Der Wert in *status überschreitet niemals MB_CUR_MAX

Beispiel

Führen Sie diesen Code aus

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
 
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
 
    char mb[MB_CUR_MAX];
    int len = wctomb(mb, wc);
    printf("wide char '%lc' -> multibyte char [", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
    printf("]\n");
}
 
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

Mögliche Ausgabe

MB_CUR_MAX = 6
State-dependent encoding? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

Referenzen

• C17-Standard (ISO/IEC 9899:2018)

• 7.22.7.3 Die Funktion wctomb (S. 261)

• K.3.6.4.1 Die Funktion wctomb_s (S. 443)

• C11-Standard (ISO/IEC 9899:2011)

• 7.22.7.3 Die Funktion wctomb (S. 358-359)

• K.3.6.4.1 Die Funktion wctomb_s (S. 610-611)

• C99-Standard (ISO/IEC 9899:1999)

• 7.20.7.3 Die Funktion wctomb (S. 322-323)

• C89/C90-Standard (ISO/IEC 9899:1990)

• 4.10.7.3 Die Funktion wctomb

Siehe auch

mbtowc	konvertiert das nächste Multibyte-Zeichen in ein Wide-Zeichen (Funktion)
wcrtombwcrtomb_s (C95)(C11)	konvertiert ein Wide-Zeichen in seine Multibyte-Darstellung, gegeben den Zustand (Funktion)
C++ Dokumentation für wctomb