mbstowcs, _mbstowcs_l

Artykuł
06/09/2015

Konwertuje ciąg znaków wielobajtowych sekwencję odpowiedniej szerokości znaków.Bardziej bezpieczne wersje tych funkcji są dostępne w 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

[Brak] wcstr
Adres sekwencji znaków szerokości.
[w] mbstr
Adres sekwencji null zakończone znaki wielobajtowe.
[in] count
Maksymalna liczba znaków wielobajtowych do konwersji.
[w] locale
Ustawienia regionalne do użycia.

Wartość zwracana

Jeśli mbstowcs pomyślnie konwertuje ciąg źródłowy zwraca numer konwertowane znaki wielobajtowe.Jeśli wcstr argument jest NULL, funkcja zwraca ciąg docelowy wymagany rozmiar (w szerokości znaków).Jeśli mbstowcs napotka nieprawidłową znaków wielobajtowych zwraca –1.Jeśli wartość zwracana jest count, wide znakowy ciąg nie jest zakończony znakiem null.

Uwaga dotycząca zabezpieczeń
Zapewnienia, że wcstr i mbstr nie pokrywają się i że count poprawnie odzwierciedla liczbę znaków wielobajtowych do konwersji.

Uwagi

mbstowcs Funkcja konwertuje do maksymalnej liczby count znaki wielobajtowe wskazywanego przez mbstr ciąg odpowiedniej szerokości znaków, które są określone przez bieżące ustawienia regionalne.Przechowuje wynikowy ciąg znaków wide pod adresem reprezentowane przez wcstr*.* Wynik jest podobna do serii połączeń w celu mbtowc.Jeśli mbstowcs napotka znak null jednobajtowe (\0), przed lub po count występuje, konwertuje znak null jest znakiem znak null (L '\0') i zatrzymuje się.Tym samym wide znakowy ciąg w wcstr jest zakończony znakiem null tylko wtedy, gdy napotka znak null podczas konwersji.Jeśli sekwencje wskazywanego 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 tym znakiem null.Ciąg źródłowy musi być zakończony znakiem null uzyskać prawidłową wartość zwracaną.Wynikowy ciąg znaków szerokości być zakończony znakiem null, należy dodać 1 do wartości zwracanych.

Jeśli mbstr argument jest NULL, lub, jeśli count jest >INT_MAX, obsługi nieprawidłowy parametr jest wywoływany, zgodnie z opisem w Sprawdzanie poprawności parametru .Jeśli wykonanie może być kontynuowana, numer błędu jest ustawiona na EINVAL i funkcja zwraca wartość -1.

mbstowcsużywa bieżących ustawień regionalnych dla wszelkich zachowań zależne od ustawień lokalnych. _mbstowcs_l jest identyczne, chyba że to korzysta z ustawień regionalnych przekazany w zamian.Aby uzyskać więcej informacji, zobacz Regionalne.

W języku programowania C++ funkcje te mają przeciążenia szablonu, które wywołują nowsze, bezpieczne odpowiedniki tych funkcji.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Wymagania

Procedura	Wymagany nagłówek
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

Dodatkowe informacje o zgodności – zobacz: Zgodność 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);
}