mbstowcs, _mbstowcs_l

Konvertiert eine Multibyte-Zeichensequenz in eine entsprechende Breitzeichensequenz. Sicherere Versionen dieser Funktionen sind verfügbar. Informationen dazu finden Sie unter mbstowcs_s, _mbstowcs_s_l.

Syntax

size_t mbstowcs(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count
);
size_t _mbstowcs_l(
   wchar_t *wcstr,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t mbstowcs(
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
size_t _mbstowcs_l(
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parameter

wcstr
Adresse einer Breitzeichensequenz.

mbstr
Adresse einer Multibyte-Zeichensequenz.

count
Die maximale Anzahl zu konvertierender Multibytezeichen.

locale
Das zu verwendende Gebietsschema.

Rückgabewert

Wenn mbstowcs die Quellzeichenfolge erfolgreich konvertiert, gibt es die Anzahl von konvertierten Multibytezeichen zurück. Wenn das wcstr-Argument NULL ist, gibt die Funktion die erforderliche Größe der Zielzeichenfolge (in Breitzeichen) zurück. Wenn mbstowcs ein ungültiges Multibytezeichen auftritt, wird -1 zurückgegeben. Wenn der Rückgabewert lautet, wird countdie Zeichenfolge mit breitem Zeichen nicht null beendet.

Hinweise

Die mbstowcs-Funktion konvertiert count-Multibytezeichen, bis zu einer maximalen Anzahl, auf die von mbstr verwiesen wird, in eine entsprechende Breitzeichenfolge, die vom aktuellen Gebietsschema angegeben werden. Es speichert die resultierende breite Zeichenfolge an der Adresse, die durch wcstrdargestellt wird. Das Ergebnis ähnelt dem einer Reihe von Aufrufen an mbtowc. Wenn mbstowcs das Single-Byte-Nullzeichen ('\0') entweder vor oder wann count auftritt, konvertiert es das NULL-Zeichen in ein breitzeicheniges Nullzeichen (L'\0') und stoppt. Folglich endet die Breitzeichen-Zeichenfolge bei wcstr nur dann auf NULL, wenn ein NULL-Zeichen während der Konvertierung erkannt wird. Wenn die Sequenzen, auf die von wcstr und mbstr verwiesen wird, überlappen, ist das Verhalten nicht definiert.

Wenn das wcstr-Argument NULL ist, gibt mbstowcs die Anzahl von Breitzeichen zurück, die bei einer Konvertierung entstehen würden; ein NULL-Terminator wird dabei nicht eingeschlossen. Die Quellzeichenfolge muss auf NULL enden, damit der korrekte Wert zurückgegeben wird. Wenn Sie wollen, dass die resultierende Breitzeichenfolge auf NULL endet, fügen Sie dem Rückgabewert 1 hinzu.

Wenn das mbstr Argument NULLlautet oder count istINT_MAX>, wird der ungültige Parameterhandler aufgerufen, wie in der Parameterüberprüfung beschrieben. Wenn die weitere Ausführung zugelassen wird, wird errno auf EINVAL gesetzt, und die Funktion gibt – 1 zurück.

mbstowcs verwendet das aktuelle Gebietsschema für jedes Verhalten, das vom Gebietsschema abhängig ist; _mbstowcs_l ist identisch, nur dass sie stattdessen das übergebene Gebietsschema verwendet. Weitere Informationen finden Sie unter Locale.

In C++ haben diese Funktionen Vorlagenüberladungen, mit denen die neueren, sicheren Entsprechungen dieser Funktionen aufgerufen werden. 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.

Anforderungen

Weitere Informationen zur Kompatibilität finden Sie unter Kompatibilität.

Beispiel

// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function

#include <stdlib.h>
#include <stdio.h>
#include <locale.h>

int main( void )
{
    size_t size;
    int nChar = 2; // number of characters to convert
    int requiredSize;

    unsigned char    *pmbnull  = NULL;
    unsigned char    *pmbhello = NULL;
    char* localeInfo;

    wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
    wchar_t *pwc;

    /* Enable the Japanese locale and codepage */
    localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
    printf("Locale information set to %s\n", localeInfo);

    printf( "Convert to multibyte string:\n" );

    requiredSize = wcstombs( NULL, pwchello, 0); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    printf("   Required Size: %d\n", requiredSize);

    /* Add one to leave room for the null terminator. */
    pmbhello = (unsigned char *)malloc( requiredSize + 1);
    if (! pmbhello)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    if (size == (size_t) (-1))
    {
        printf("Couldn't convert string. Code page 932 may"
                " not be available.\n");
        return 1;
    }
    printf( "   Number of bytes written to multibyte string: %u\n",
            (unsigned int) size );
    printf( "   Hex values of the" );
    printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
            pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
    printf( "   Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");

    printf( "Convert back to wide-character string:\n" );

    /* Assume we don't know the length of the multibyte string.
     Get the required size in characters, and allocate enough space. */

    requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
    /* Add one to leave room for the null terminator */
    pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
    if (! pwc)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
    if (size == (size_t) (-1))
    {
       printf("Couldn't convert string--invalid multibyte character.\n");
    }
    printf( "   Characters converted: %u\n", (unsigned int)size );
    printf( "   Hex value of first 2" );
    printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
    free(pwc);
    free(pmbhello);
}

Locale information set to Japanese_Japan.932
Convert to multibyte string:
   Required Size: 4
   Number of bytes written to multibyte string: 4
   Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1
   Codepage 932 uses 0x81 to 0x9f as lead bytes.

Convert back to wide-character string:
   Characters converted: 2
   Hex value of first 2 wide characters: 0x3042 0x3043

Siehe auch

Datenkonvertierung
Gebietsschema
Interpretation von Multibytezeichensequenzen
_mbclen, mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar