Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Определено в заголовочном файле <stdlib.h>
(1)
size_t mbstowcs ( wchar_t * dst, const char * src, size_t len )
(до C99)
size_t mbstowcs ( wchar_t * restrict dst, const char * restrict src, size_t len )
(начиная с C99)
errno_t mbstowcs_s ( size_t * restrict retval, wchar_t * restrict dst,
rsize_t dstsz, const char * restrict src, rsize_t len ) ;
(2) (начиная с C11)
1) Преобразует многобайтовую строку символов из массива, на первый элемент которого указывает src , в её широкосимвольное представление. Преобразованные символы сохраняются в последовательных элементах массива, на который указывает dst . Не более чем len широких символов записывается в целевой массив.
Каждый символ преобразуется как при вызове функции mbtowc , за исключением того, что состояние преобразования mbtowc не изменяется. Преобразование останавливается, если:
* Многобайтовый нулевой символ был преобразован и сохранён.
* Встречен недопустимый (в текущей локали C) многобайтовый символ.
* Следующий широкий символ, который должен быть сохранён, превысит len .
Если src и dst перекрываются, поведение не определено
2) То же, что и (1) , за исключением того, что
* преобразование выполняется как будто с помощью mbrtowc , а не mbtowc
* функция возвращает свой результат через выходной параметр retval
* если нулевой символ не был записан в dst после записи len широких символов, тогда L ' \0 ' сохраняется в dst[len] , что означает запись len+1 всего широких символов
* если dst является нулевым указателем, количество широких символов, которое было бы сгенерировано, сохраняется в * retval
* функция затирает массив назначения от завершающего нуля и до dstsz
* Если src и dst перекрываются, поведение не определено.
* следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную constraint handler функцию:
  • retval или src является нулевым указателем
  • dstsz или len больше чем RSIZE_MAX/sizeof(wchar_t) (если только dst не является нулевым)
  • dstsz не равно нулю (если только dst не является нулевым)
  • В первых dstsz многобайтовых символах массива src отсутствует нулевой символ и len больше чем dstsz (если только dst не является нулевым)
Как и все функции с проверкой границ, mbstowcs_s гарантированно доступна только если __STDC_LIB_EXT1__ определено реализацией и если пользователь определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1 перед включением <stdlib.h> .

Содержание

Примечания

В большинстве реализаций mbstowcs обновляет глобальный статический объект типа mbstate_t в процессе обработки строки и не может быть вызван одновременно из двух потоков. mbsrtowcs следует использовать в таких случаях.

POSIX определяет общее расширение: если dst является нулевым указателем, эта функция возвращает количество широких символов, которые были бы записаны в dst , при преобразовании. Аналогичное поведение стандартно для mbstowcs_s и для mbsrtowcs .

Параметры

dst - указатель на массив широких символов, в котором будет сохранена широкая строка
src - указатель на первый элемент многобайтовой строки с нулевым завершителем для преобразования
len - количество широких символов, доступных в массиве, на который указывает dst
dstsz - максимальное количество широких символов, которое будет записано (размер массива dst )
retval - указатель на объект size_t, в котором будет сохранен результат

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

1) При успешном выполнении возвращает количество широких символов, исключая завершающий L ' \0 ' , записанных в целевой массив. При ошибке преобразования (если встречен недопустимый многобайтовый символ) возвращает ( size_t ) - 1 .
2) ноль при успехе (в этом случае количество широких символов, исключая завершающий ноль, которые были или были бы записаны в dst , сохраняется в * retval ), не ноль при ошибке. В случае нарушения ограничения времени выполнения, сохраняет ( size_t ) - 1 в * retval (если retval не является нулевым указателем) и устанавливает dst [ 0 ] в L ' \0 ' (если dst не является нулевым указателем или dstmax не равен нулю или не больше RSIZE_MAX )

Пример

Запустить этот код 
#include <stdio.h>
#include <locale.h>
#include <stdlib.h>
#include <wchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

Вывод: 

MB string: zß水🍌
Wide string: zß水🍌

Ссылки

  • Стандарт C11 (ISO/IEC 9899:2011):
  • 7.22.8.1 Функция mbstowcs (стр. 359)
  • K.3.6.5.1 Функция mbstowcs_s (стр. 611-612)
  • Стандарт C99 (ISO/IEC 9899:1999):
  • 7.20.8.1 Функция mbstowcs (стр. 323)
  • Стандарт C89/C90 (ISO/IEC 9899:1990):
  • 4.10.8.1 Функция mbstowcs

Смотрите также

(C95) (C11)
преобразует строку многобайтовых символов в широкую строку с учетом состояния
(функция)
(C11)
преобразует широкую строку в строку многобайтовых символов
(функция)
Документация C++ для mbstowcs