Namespaces
Variants

wctomb, wctomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definiert in 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 Breitzeichen wc in eine Multibyte-Kodierung um und speichert es (einschließlich aller Shift-Sequenzen) im char-Array, dessen erstes Element durch s gezeigt wird. Es werden maximal MB_CUR_MAX Zeichen gespeichert. Die Konvertierung wird durch die LC_CTYPE-Kategorie der aktuellen Locale beeinflusst.
Wenn wc das Nullzeichen ist, wird das Nullbyte in s geschrieben, vorangestellt von allen Shift-Sequenzen, die notwendig sind, um den initialen Shift-Zustand wiederherzustellen.
Wenn s ein Nullzeiger ist, setzt diese Funktion den globalen Konvertierungszustand zurück und bestimmt, ob Shift-Sequenzen verwendet werden.
2) Gleich wie (1) , außer dass das Ergebnis im Out-Parameter status zurückgegeben wird und die folgenden Fehler zur Laufzeit erkannt werden und den aktuell installierten constraint handler aufrufen:
  • ssz ist kleiner als die Anzahl der Bytes, die geschrieben würden (sofern s nicht null ist)
  • ssz ist größer als RSIZE_MAX (sofern s nicht null ist)
  • 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__ durch die Implementierung definiert ist und wenn der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 setzt, bevor <stdlib.h> eingebunden wird.

Inhaltsverzeichnis

Hinweise

Jeder Aufruf von wctomb aktualisiert den internen globalen Konvertierungszustand (ein statisches Objekt vom Typ mbstate_t , der nur dieser Funktion bekannt ist). Wenn die Multibyte-Kodierung Shift-Zustände verwendet, ist diese Funktion nicht wiedereintrittsfähig. In jedem Fall sollten mehrere Threads wctomb nicht ohne Synchronisierung aufrufen: wcrtomb oder wctomb_s können stattdessen verwendet werden.

Im Gegensatz zu den meisten grenzprüfenden Funktionen, wctomb_s nullterminiert seine Ausgabe nicht, da es für die Verwendung in Schleifen konzipiert ist, die Zeichenketten zeichenweise verarbeiten.

Parameter

s - Zeiger auf das Zeichenarray für die Ausgabe
wc - zu konvertierendes Breitzeichen
ssz - maximale Anzahl an Bytes, die in s geschrieben werden (Größe des Arrays s )
status - Zeiger auf einen Ausgabeparameter, in dem das Ergebnis (Länge der Multibyte-Sequenz oder Status der Schichtsequenz) 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 falls wc kein gültiges Zeichen ist.
Wenn s ein Nullzeiger ist, setzt es seinen internen Konvertierungszustand zurück, um den anfänglichen Shift-Zustand darzustellen, und gibt ​ 0 ​ zurück, wenn die aktuelle Multibyte-Kodierung zustandsunabhängig ist (keine Shift-Sequenzen verwendet) oder einen Wert ungleich Null, wenn die aktuelle Multibyte-Kodierung zustandsabhängig ist (Shift-Sequenzen verwendet).
2) Null bei Erfolg, wobei die Multibyte-Darstellung von wc in s gespeichert wird und ihre Länge in * status gespeichert wird, oder, falls s null ist, der Shift-Sequenz-Status in status gespeichert wird). Nicht-Null bei Kodierungsfehler oder Laufzeitbedingungsverletzung, wobei ( size_t ) - 1 in * status gespeichert wird. Der in * status gespeicherte Wert überschreitet niemals MB_CUR_MAX

Beispiel

Diesen Code ausführen 
#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 wctomb-Funktion (S: 261)
  • K.3.6.4.1 Die wctomb_s-Funktion (S: 443)
  • C11-Standard (ISO/IEC 9899:2011):
  • 7.22.7.3 Die wctomb-Funktion (S: 358-359)
  • K.3.6.4.1 Die wctomb_s-Funktion (S: 610-611)
  • C99-Standard (ISO/IEC 9899:1999):
  • 7.20.7.3 Die wctomb-Funktion (S. 322-323)
  • C89/C90 Standard (ISO/IEC 9899:1990):
  • 4.10.7.3 Die wctomb-Funktion

Siehe auch

wandelt das nächste Multibyte-Zeichen in ein Breitzeichen um
(Funktion)
(C95) (C11)
wandelt ein Breitzeichen in seine Multibyte-Darstellung um, mit Zustand
(Funktion)
C++-Dokumentation für wctomb