mbstowcs, _mbstowcs_l

  • Статья

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

Параметры

wcstr
Адрес последовательности расширенных символов.

mbstr
Адрес последовательности многобайтовых символов, заканчивающейся нуль-символом.

count
Наибольшее число многобайтовых символов для преобразования.

locale
Используемый языковой стандарт.

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

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

Важно!

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

Замечания

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

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

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

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

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

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Требования

Маршрут Обязательный заголовок
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);
}

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

См. также

Преобразование данных
Локаль
Интерпретация последовательностей многобайтовых символов
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar