Namespaces
Variants

    wcrtomb, wcrtomb_s

    Von de.cppreference.net
     
    C
     
    Zeichenketten-Bibliothek
     
    Nullterminierte Multibyte-Zeichenketten
     
    Definiert in Header <wchar.h> 
    size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);
    		(1) (seit C95)
    (bis C99)    		 
    size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);
    		(seit C99) 
    errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);
    		(2) (seit C11)

    Konvertiert ein weites Zeichen in seine schmale Multibyte-Darstellung.

    1) Falls s kein Nullzeiger ist, bestimmt die Funktion die Anzahl von Bytes, die zum Speichern der Multibyte-Zeichendarstellung von wc erforderlich ist (einschließlich etwaiger Umschaltsequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungszustands *ps), und speichert die Multibyte-Zeichendarstellung in dem Zeichenarray, dessen erstes Element von s referenziert wird, und aktualisiert *ps nach Bedarf. Es können höchstens MB_CUR_MAX Bytes von dieser Funktion geschrieben werden.
    Falls s ein Nullzeiger ist, ist der Aufruf äquivalent zu wcrtomb(buf, L'\0', ps) für einen internen Puffer buf.
    Falls wc das weite Nullzeichen L'\0' ist, wird ein Nullbyte gespeichert, dem jegliche Umschaltsequenzen vorangestellt werden, die nötig sind, um den Anfangsumschaltzustand wiederherzustellen, und der Konvertierungszustandsparameter *ps wird aktualisiert, um den Anfangsumschaltzustand darzustellen.
    Falls das Umgebungsmakro __STDC_ISO_10646__ definiert ist, sind die Werte des Typs wchar_t dieselben wie die Kurznamen der Zeichen im Unicode-Required-Set (typischerweise UTF-32-Kodierung); andernfalls ist es implementierungsdefiniert. In jedem Fall wird die von dieser Funktion verwendete Multibyte-Zeichenkodierung durch das aktuell aktive C-Locale festgelegt.
    2) Wie (1), außer dass
    falls s ein Nullzeiger ist, der Aufruf äquivalent zu wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) mit internen Variablen retval und buf ist (deren Größe größer ist als MB_CUR_MAX)
    das Ergebnis im Ausgabeparameter retval
    zurückgegeben wird die folgenden Fehler zur Laufzeit erkannt werden und die derzeit installierte Constraint-Handler-Funktion aufrufen:
    • retval oder ps ist ein Nullzeiger.
    • ssz ist Null oder größer als RSIZE_MAX (außer wenn s Null ist)
    • ssz ist kleiner als die Anzahl der Bytes, die geschrieben würden (außer wenn s Null ist)
    • s ist ein Nullzeiger, aber ssz ist nicht Null
    Wie bei allen bounds-geprüften Funktionen ist wcrtomb_s nur dann garantiert verfügbar, wenn __STDC_LIB_EXT1__ von der Implementierung definiert ist und der Benutzer __STDC_WANT_LIB_EXT1__ auf die Integer-Konstante 1 definiert, bevor er <wchar.h> einbindet.

    Parameter

    s - Zeiger auf schmales Zeichenarray, in dem das Multibyte-Zeichen gespeichert wird
    wc - das zu konvertierende weite Zeichen
    ps - Zeiger auf das Konvertierungszustandsobjekt, das bei der Interpretation der Multibyte-Zeichenkette verwendet wird
    ssz - maximale Anzahl zu schreibender Bytes (die Größe des Puffers s)
    retval - Zeiger auf einen Ausgabeparameter, in dem das Ergebnis (Anzahl der Bytes in der Multibyte-Zeichenkette einschließlich etwaiger Umschaltsequenzen) gespeichert wird

    Rückgabewert

    1) Bei Erfolg wird die Anzahl der Bytes (einschließlich etwaiger Umschaltsequenzen) zurückgegeben, die in das Zeichenarray geschrieben wurden, dessen erstes Element von s referenziert wird.
    Bei Fehler (wenn wc kein gültiges weites Zeichen ist) wird (size_t)-1 zurückgegeben, EILSEQ in errno gespeichert und *ps in einem nicht spezifizierten Zustand hinterlassen.
    2) Gibt bei Erfolg Null und bei Fehler einen von Null verschiedenen Wert zurück, wobei s[0] auf '\0' gesetzt wird (außer wenn s Null ist oder ssz Null oder größer als RSIZE_MAX ist) und *retval auf (size_t)-1 gesetzt wird (außer wenn retval Null ist)

    Beispiel

    Diesen Code ausführen
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -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("%#x ", +(unsigned char)out[x]);
    puts("]");
}

    Ausgabe: 

    Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

    Referenzen

    • C23-Standard (ISO/IEC 9899:2024):
    • 7.29.6.3.3 Die wcrtomb-Funktion (p: TBD)
    • K.3.9.3.1.1 Die wcrtomb_s-Funktion (p: TBD)
    • C17-Standard (ISO/IEC 9899:2018):
    • 7.29.6.3.3 Die wcrtomb-Funktion (p: TBD)
    • K.3.9.3.1.1 Die wcrtomb_s-Funktion (p: TBD)
    • C11-Standard (ISO/IEC 9899:2011):
    • 7.29.6.3.3 Die wcrtomb-Funktion (p: 444)
    • K.3.9.3.1.1 Die wcrtomb_s-Funktion (p: 647-648)
    • C99-Standard (ISO/IEC 9899:1999):
    • 7.24.6.3.3 Die wcrtomb-Funktion (p: 390)

    Siehe auch

    (C11)
    		 konvertiert ein weites Zeichen in seine Multibyte-Darstellung
    (Funktion)
    (C95)
    		 konvertiert das nächste Multibyte-Zeichen in ein weites Zeichen, gegebenen Zustand
    (Funktion)
    C++Dokumentation für wcrtomb