mbstowcs, _mbstowcs_l

Статья
02/20/2013

Преобразует последовательность многобайтовых символов для соответствующей последовательности расширенных символов.Более безопасные версии этих функций доступны; см. 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

Параметры

[out] wcstr
Адрес последовательности расширенных символов.
[in] mbstr
Адрес последовательности null был завершен многобайтовая кодировка.
[входящий] count
Максимальное количество многобайтовых символов, которую необходимо преобразовать.
[входящий] locale
Языковой стандарт, который необходимо использовать.

Возвращаемое значение

If mbstowcs успешно выполнит преобразование строки источника, он возвращает число преобразованных многобайтовых символов.Если wcstr аргумент NULLфункция возвращает необходимый размер (в символах) строки расширенных назначения.If mbstowcs многобайтовый встречает недопустимый символ возвращается - 1.Если возвращаемое значение count(строка символов null-не завершена.

Примечание по безопасности
Убедитесь, что wcstr и mbstr не перекройте и count правильно отражает количество многобайтовых символов для преобразования.

Заметки

mbstowcs функция преобразует до максимального числа count многобайтовая кодировка указанные к которым следуют mbstr в строке соответствующую расширенных символов, которые определяются текущим языковым стандартом.Он сохраняет результирующая строка символов по адресу, представленном by wcstr*.* Результат аналогичен ряда вызовов mbtowc.If mbstowcs встречает (" нуль-символа единый-байта \ 0 "), либо до или после count происходит, нуль-символ к нуль-символу он выполняется преобразование расширенных символов (L \ 0 ') и останавливается.Таким образом, строка символов на wcstr null-завершит, только если нуль-символ встречается во время преобразования.Если последовательности указали к которым следуют wcstr и mbstr перекрытие, расширения функциональности не определено.

Если wcstr аргумент NULL" mbstowcs возвращает количество расширенных символов, которые привели бы в результате преобразования, не включая символ конца строки null.Строка источника должен null-завершить для правильного возвращаемого значения.Если требуется результирующая строка символов юникода быть завершенным, добавьте его к возвращаемому значению.

Если mbstr аргумент NULLили count > INT_MAXнедопустимый параметр, обработчик вызывается, как описано в разделе Проверка параметров .Если выполнение может продолжить, errno имеет значение EINVAL и функция возвращает значение -1.

mbstowcs использует текущий языковой стандарт для любого расширения функциональности, зависимых от языковых стандартов. _mbstowcs_lидентичны, за исключением того, что он использует языковой стандарт переданный.Дополнительные сведения см. в разделе Языковой стандарт.

В C++, эти функции имеют перегруженные версии шаблона, вызывающих более новые безопасные аналогом этих функций.Дополнительные сведения см. в разделе Предоставляйте перегруженный шаблона.

Требования

Процедура	Обязательный заголовок
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

Дополнительные сведения о совместимости см. Совместимость во введении.

Пример

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