wcrtomb

Konvertieren von Breitzeichen in die Multibyte-Zeichendarstellung. Eine sicherere Version dieser Funktion ist verfügbar; siehe wcrtomb_s.

Syntax

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

Parameter

mbchar
Das resultierende in Multibyte konvertierte Zeichen.

wchar
Ein zu konvertierendes Breitzeichen.

mbstate
Ein Zeiger auf ein mbstate_t -Objekt.

Rückgabewert

Gibt die Anzahl der Bytes zurück, die erforderlich sind, um das konvertierte Multibytezeichen darzustellen, oder andernfalls -1, wenn ein Fehler auftritt.

Hinweise

Die Funktion wcrtomb konvertiert ein Breitzeichen, beginnend beim angegebenen Konvertierungsstatus, der in mbstate enthalten ist, vom in wchar enthaltenen Wert in die von mbchar dargestellte Adresse. Der Rückgabewert ist die Anzahl der Bytes, die erforderlich sind, um das entsprechende Multibytezeichen darzustellen. Es werden jedoch höchstens MB_CUR_MAX Bytes zurückgegeben.

Wenn mbstate NULL ist, wird das interne mbstate_t-Objekt verwendet, das den Konvertierungsstatus von mbchar enthält. Wenn die Zeichensequenz wchar keine entsprechende Multibyte-Zeichendarstellung enthält, wird ein -1 zurückgegeben, und der errno Wert wird auf EILSEQ. festgelegt.

Die wcrtomb Funktion unterscheidet sich von wctombder _wctomb_l Neustartbarkeit. Der Konvertierungszustand wird für nachfolgende Aufrufe der gleichen oder anderer Funktionen, die neu gestartet werden können, in mbstate gespeichert. Wenn sowohl Funktionen, die neu gestartet werden können, als auch Funktionen, die nicht neu gestartet werden könnnen, verwendet werden, sind die Ergebnisse undefiniert. Beispiel: Eine Anwendung würde wcsrlen anstelle von wcsnlen verwenden, wenn ein nachfolgender Aufruf von wcsrtombs anstelle von wcstombs verwendet würde.

In C++ hat diese Funktion eine Vorlagenüberladung, mit der die neuere, sichere Entsprechung dieser Funktion aufgerufen wird. Weitere Informationen finden Sie unter Secure Template Overloads.

Standardmäßig gilt der globale Zustand dieser Funktion für die Anwendung. Wie Sie dieses Verhalten ändern, erfahren Sie unter Globaler Status in der CRT.

Ausnahmen

Die wcrtomb-Funktion ist multithreadsicher, solange keine Funktion im aktuellen Thread setlocale aufruft, während diese Funktion ausgeführt wird und mbstate NULL ist.

Beispiel

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to the "Q" multibyte character.

Anforderungen

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
mbsinit