mbsrtowcs, mbsrtowcs_s

Определено в заголовочном файле <wchar.h>

Определено в заголовочном файле `<wchar.h>`
size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );	(1)	(начиная с C95) (до C99)
size_t mbsrtowcs( wchar_t restrict dst, const char restrict src, size_t len, mbstate_t restrict ps );		(начиная с C99)
errno_t mbsrtowcs_s( size_t restrict retval, wchar_t restrict dst, rsize_t dstsz, const char *restrict src, rsize_t len, mbstate_t restrict ps );	(2)	(начиная с C11)

size_t mbsrtowcs( wchar_t* dst, const char** src, size_t len, mbstate_t* ps );

(1)

(начиная с C95)
(до C99)

size_t mbsrtowcs( wchar_t *restrict dst, const char **restrict src, size_t len,
                  mbstate_t *restrict ps );

(начиная с C99)

errno_t mbsrtowcs_s( size_t *restrict retval,
                     wchar_t *restrict dst, rsize_t dstsz,
                     const char **restrict src, rsize_t len,
                     mbstate_t *restrict ps );

(2)

(начиная с C11)

1) Преобразует завершающуюся нулевым символом многобайтовую последовательность символов, начинающуюся в состоянии преобразования, описанном в *ps, из массива, первый элемент которого указывает на *src, в её широкосимвольное представление. Если dst не является нулевым указателем, преобразованные символы сохраняются в последовательных элементах массива wchar_t, на который указывает dst. В массив назначения записывается не более len широких символов. Каждый многобайтовый символ преобразуется так, как если бы был выполнен вызов mbrtowc. Преобразование прекращается, если:

Преобразован и сохранён многобайтовый нулевой символ. *src присваивается значение нулевого указателя, а *ps представляет начальное состояние сдвига.
Обнаружен недопустимый многобайтовый символ (согласно текущей локали C). *src указывает на начало первого непреобразованного многобайтового символа.
Следующий записываемый широкий символ превысит len. *src указывает на начало первого непреобразованного многобайтового символа. Это условие не проверяется, если dst является нулевым указателем.

2) То же, что и (1), за исключением того, что

функция возвращает результат через выходной параметр retval
если после записи len широких символов в dst не был записан нулевой символ, то в dst[len] сохраняется L'\0', то есть записывается всего len+1 широких символов
функция перезаписывает массив назначения, начиная с завершающего нулевого символа и до dstsz
Если src и dst перекрываются, поведение не определено.
во время выполнения обнаруживаются следующие ошибки, при возникновении которых вызывается установленная в данный момент функция обработчика ограничений:

retval, ps, src или *src является нулевым указателем
dstsz или len больше, чем RSIZE_MAX/sizeof(wchar_t) (если только dst не является нулевым указателем)
dstsz не равно нулю (если только dst не является нулевым указателем)
В первых dstsz многобайтовых символах массива *src отсутствует нулевой символ, а len больше, чем dstsz (если только dst не является нулевым указателем)

Как и для всех функций с проверкой границ, доступность mbsrtowcs_s гарантируется только в том случае, если реализация определяет __STDC_LIB_EXT1__, а пользователь перед включением <wchar.h> определяет __STDC_WANT_LIB_EXT1__ как целочисленную константу 1.

Параметры

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

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

1) В случае успеха возвращает количество широких символов, не включая завершающий L'\0', записанных в массив символов. Если dst является нулевым указателем, возвращает количество широких символов, которое было бы записано при неограниченной длине. В случае ошибки преобразования (если обнаружен недопустимый многобайтовый символ) возвращает (size_t)-1, сохраняет EILSEQ в errno и оставляет *ps в неопределённом состоянии.

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

Пример

#include <stdio.h>
#include <locale.h>
#include <wchar.h>
#include <string.h>

void print_as_wide(const char* mbstr)
{
    mbstate_t state;
    memset(&state, 0, sizeof state);
    size_t len = 1 + mbsrtowcs(NULL, &mbstr, 0, &state);
    wchar_t wstr[len];
    mbsrtowcs(&wstr[0], &mbstr, len, &state);
    wprintf(L"Wide string: %ls \n", wstr);
    wprintf(L"The length, including L'\\0': %zu\n", len);
}

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    print_as_wide(u8"z\u00df\u6c34\U0001f34c"); // u8"zß水🍌"
}

Вывод:

Wide string: zß水🍌
The length, including L'\0': 5

Ссылки

Стандарт C11 (ISO/IEC 9899:2011):

7.29.6.4.1 Функция mbsrtowcs (стр. 445)
K.3.9.3.2.1 Функция mbsrtowcs_s (стр. 648–649)

Стандарт C99 (ISO/IEC 9899:1999):

7.24.6.4.1 Функция mbsrtowcs (стр. 391)

См. также

mbstowcsmbstowcs_s (C11)	преобразует узкую многобайтовую строку символов в широкую строку (функция)
mbrtowc (C95)	преобразует следующий многобайтовый символ в широкий символ с учётом состояния (функция)
wcsrtombswcsrtombs_s (C95)(C11)	преобразует широкую строку в узкую многобайтовую строку символов с учётом состояния (функция)
Документация C++ для `mbsrtowcs`

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