Share via

mbstowcs, _mbstowcs_l

  • Artykuł

Konwertuje sekwencję znaków wielobajtowych na odpowiednią sekwencję znaków szerokich. Dostępne są bezpieczniejsze wersje tych funkcji; zobacz mbstowcs_s, _mbstowcs_s_l.

Składnia

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

wcstr
Adres sekwencji znaków szerokich.

mbstr
Adres sekwencji znaków wielobajtowych zakończonych o wartości null.

count
Maksymalna liczba znaków wielobajtowych do przekonwertowania.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Jeśli mbstowcs ciąg źródłowy zostanie pomyślnie przekonwertowany, zwraca liczbę przekonwertowanych znaków wielobajtowych. wcstr Jeśli argument to NULL, funkcja zwraca wymagany rozmiar (w szerokich znakach) ciągu docelowego. Jeśli mbstowcs napotka nieprawidłowy znak wielobajtowy, zwraca wartość -1. Jeśli zwracana wartość to count, ciąg o szerokim znaku nie jest zakończony wartością null.

Ważne

Upewnij się, że wcstr i mbstr nie nakładają się, i że count poprawnie odzwierciedla liczbę znaków wielobajtowych do konwersji.

Uwagi

Funkcja mbstowcs konwertuje maksymalną liczbę count znaków wielobajtowych wskazywanych przez mbstr ciąg odpowiadających im znaków szerokich, które są określane przez bieżące ustawienia regionalne. Przechowuje wynikowy ciąg o szerokim znaku na adresie reprezentowanym przez wcstrelement . Wynik jest podobny do serii wywołań funkcji mbtowc. Jeśli mbstowcs napotka znak null pojedynczego bajtu (\0) przed lub w przypadku count wystąpienia, konwertuje znak null na znak null (L'\0') i zatrzymuje się. W związku z tym ciąg znaków szeroki w wcstr obiekcie jest zakończony wartością null tylko wtedy, gdy podczas konwersji napotkano znak null. Jeśli sekwencje wskazywane przez wcstr i mbstr nakładają się na siebie, zachowanie jest niezdefiniowane.

wcstr Jeśli argument ma NULLwartość , mbstowcs zwraca liczbę znaków szerokich, które mogłyby wynikać z konwersji, a nie włącznie z terminatorem o wartości null. Aby zwracać prawidłową wartość, ciąg źródłowy musi być zakończony wartością null. Jeśli chcesz, aby wynikowy ciąg znaków był zakończony ciągiem o wartości null, dodaj jeden do zwracanej wartości.

mbstr Jeśli argument ma NULLwartość , lub count , >INT_MAXwywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, jest ustawione na EINVAL , errno a funkcja zwraca wartość -1.

mbstowcs używa bieżących ustawień regionalnych dla dowolnego zachowania zależnego od ustawień regionalnych; _mbstowcs_l jest identyczna, z tą różnicą, że używa ustawień regionalnych przekazanych w zamian. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

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

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Wymagania

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

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

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

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

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar