mbstowcs, _mbstowcs_l

Artykuł
02/27/2013

Konwertuje sekwencja znaków wielobajtowych do odpowiedniej sekwencji szerokości znaków.Bezpieczniejsze wersje te funkcje są dostępne; see 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

Parametry

[out]wcstr
Adres sekwencji szerokości znaków.
[w]mbstr
Adres sekwencji null zakończone znaki wielobajtowe.
[w]count
Maksymalna liczba znaków wielobajtowych do konwertowania.
[w]locale
Ustawienia regionalne, aby użyć.

Wartość zwracana

Jeśli mbstowcs pomyślnie konwertuje ciąg źródłowy zwraca liczbę konwertowane znaki wielobajtowe.Jeśli wcstr argument jest NULL, funkcja zwraca wymagany rozmiar (w znakach szeroki) Ciąg docelowego.Jeśli mbstowcs napotka nieprawidłowych znaków wielobajtowych zwraca –1.Jeśli wartość zwracana jest count, łańcuch szerokich znaków nie jest zakończony znakiem null.

Uwaga dotycząca zabezpieczeń
Zapewnić, że wcstr i mbstr nie nakładają się i że count poprawnie odzwierciedla liczba znaków wielobajtowych do konwertowania.

Uwagi

mbstowcs Funkcja konwertuje do maksymalnej liczby count znaki wielobajtowe wskazywanej przez mbstr ciąg odpowiedniej szerokości znaków, które są określane przez bieżące ustawienia regionalne.Przechowuje on wynikowy ciąg znaków wide pod adresem, reprezentowana przez wcstr*.* Wynik jest podobne do serii wywołania mbtowc.Jeśli mbstowcs napotka znak null jednobajtowe (\0), przed lub po count występuje znak null do szerokich znaków znakiem null (L '\0') i zatrzymuje są konwertowane.Ten sposób łańcuch szerokich znaków na wcstr jest zakończony zerem tylko wtedy, gdy napotka znak null podczas konwersji.Jeśli sekwencji wskazywanej przez wcstr i mbstr nakładające się, zachowanie jest niezdefiniowane.

Jeśli wcstr argument jest NULL, mbstowcs zwraca liczbę szerokości znaków, które byłyby wynikiem konwersji, nie włączając null terminator.Ciąg źródłowy musi być zakończony zerem poprawne wartości zwracane.Jeśli wynikowy ciąg znaków szerokości za zakończony znakiem null, należy dodać do wartości zwracane.

If the mbstr argument is NULL, or if count is > INT_MAX, wywoływana jest funkcja obsługi nieprawidłowy parametr, jak opisano w Sprawdzanie poprawności parametru .Jeśli wykonanie może kontynuować, errno jest ustawiona na EINVAL i funkcja zwraca wartość -1.

mbstowcswykorzystuje bieżące ustawienia regionalne dla wszelkich zachowanie zależnego od ustawień regionalnych; _mbstowcs_l jest identyczny z wyjątkiem, że korzysta z ustawień regionalnych, przekazany w zamian.Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++ funkcje te mają overloads szablonu, które wywołują nowsze, bezpieczne odpowiednikami tych funkcji.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

Aby uzyskać dodatkowe informacje o zgodności, zobacz zgodności we wprowadzeniu.

Przykład

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