mbstowcs, _mbstowcs_l

Artikel
02/26/2013

Konvertiert eine Sequenz von Mehrbytezeichen eine geeignete Sequenz von Breitzeichen.Sicherere Versionen dieser Funktionen sind verfügbar. Weitere Informationen finden Sie unter mbstowcs_s, _mbstowcs_s_l.

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

[out] wcstr
Die Adresse einer Sequenz von Breitzeichen.
[in] mbstr
Die Adresse einer Sequenz von NULL beendete Mehrbytezeichen.
[in] count
Die maximale Anzahl der zu konvertierenden Mehrbytezeichen.
[in] locale
Das zu verwendende Gebietsschema.

Rückgabewert

Wenn die Quellzeichenfolge mbstowcs erfolgreich konvertiert, gibt sie die Anzahl der konvertierten Mehrbytezeichen zurück.Wenn das Argument wcstrNULList, gibt die Funktion die erforderliche Größe (in Breitzeichen) der Zielzeichenfolge zurück.Wenn mbstowcs ein ungültiges Mehrbytezeichen findet, gibt sie 1 zurück.Wenn der Rückgabewert countist, wird die Zeichenfolge mit Breitzeichen nicht auf NULL.

Sicherheitshinweis
Stellen Sie sicher, dass wcstr und mbstr sich nicht überschneiden und dass count ordnungsgemäß die Anzahl der Mehrbytezeichen auf Convert widerspiegelt.

Hinweise

Die mbstowcs-Funktion konvertiert bis zu einer maximalen Anzahl count Mehrbytezeichen, die durch mbstr auf eine Zeichenfolge mit Breitzeichen entsprechenden dargestellt werden, die durch das aktuelle Gebietsschema bestimmt werden.Sie speichert die resultierende Zeichenfolge mit Breitzeichen an der Adresse, die von wcstrdargestellt wird*.* Das Ergebnis ist eine Reihe von Aufrufen mbtowcvergleichbar.Wenn das mbstowcs Einzelbyte- null-zeichen („\ 0 ") entweder vor oder auftritt, wenn sie auftritt, count das NULL-Zeichen zu einem NULL-Breitzeichen (L \ 0 ') konvertiert und beendet wird.Daher ist die Zeichenfolge mit Breitzeichen unter wcstr auf NULL endende nur, wenn ein NULL-Zeichen bei der Konvertierung gefunden wird.Wenn die Sequenzen, die über wcstr und mbstr Überlappung, das Verhalten dargestellt werden, nicht definiert ist.

Wenn das Argument wcstrNULList, gibt mbstowcs die Anzahl der Breitzeichen, die sich aus der Konvertierung bewirken würden, ohne ein NULL-Abschlusszeichen zurück.Die Quellzeichenfolge muss auf NULL endende sein, damit der richtige Wert zurückgegeben werden kann.Wenn Sie die resultierende Zeichenfolge mit Breitzeichen auf NULL endende sein müssen, fügen Sie den zurückgegebenen Wert hinzu.

Wenn das Argument mbstrNULList oder wenn count > INT_MAXungültige Parameter ist, wird der Ereignishandler aufgerufen, wie in Parametervalidierung beschrieben.Wenn die Ausführung zulässig ist, um fortzufahren, wird errno zu EINVAL festgelegt, und die Funktion gibt -1 zurück.

mbstowcs verwendet das aktuelle Gebietsschema für ein beliebiges gebietsschemaabhängige Verhalten. _mbstowcs_list identisch, mit der Ausnahme, dass sie verwendet das Gebietsschema, das Stattdessen übergeben wird.Weitere Informationen finden Sie unter Gebietsschema.

In C++ haben Überladungen Vorlagen, die diese Funktionen aufrufen, um das neueres, Entsprechungen dieser Funktionen.Weitere Informationen finden Sie unter Speichern Sie Vorlagen-Überladungen.

Anforderungen

Routine	Erforderlicher Header
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

Um Kompatibilität zusätzlichen Informationen finden Sie unter Kompatibilität in der Einführung.

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);
}