mbstowcs, mbstowcs_s

Определено в заголовке `<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 широких символов, то в dst[len] сохраняется L'\0', что означает, что всего записываются len+1 широких символов

* Если dst является указателем на нуль, количество широких символов, которые были бы произведены, сохраняется в *retval

* функция очищает массив назначения от завершающего нуля и до dstsz

* Если src и dst перекрываются, поведение не определено.

* следующие ошибки обнаруживаются во время выполнения и вызывают текущую установленную функцию обработчика ограничений обработчика ограничений:

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), ненулевое значение при ошибке. В случае нарушения ограничения во время выполнения, в *retval хранится (size_t)-1 (если 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

См. также

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

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/c/string/multibyte/mbstowcs