mbstowcs, mbstowcs_s

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

Определено в заголовочном файле `<stdlib.h>`
size_t mbstowcs( wchar_t* dst, const char* src, size_t len)	(1)	(до 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)

size_t mbstowcs( wchar_t* dst, const char* src, size_t len)

(1)

(до 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
если после записи len широких символов в dst не был записан нулевой символ, то в 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), ненулевое значение в случае ошибки. При нарушении ограничения во время выполнения сохраняет (size_t)-1 в *retval (если только retval не является нулевым указателем) и устанавливает dst[0] в L'\0' (если только dst не является нулевым указателем, dstmax не равен нулю и не больше RSIZE_MAX)

Пример

#include <locale.h>
#include <stdio.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ß水🍌

Ссылки

Стандарт C23 (ISO/IEC 9899:2024):

7.22.8.1 Функция mbstowcs (стр.: TBD)
K.3.6.5.1 Функция mbstowcs_s (стр.: TBD)

Стандарт C17 (ISO/IEC 9899:2018):

7.22.8.1 Функция mbstowcs (стр.: TBD)
K.3.6.5.1 Функция mbstowcs_s (стр.: TBD)

Стандарт 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/c/string/multibyte/mbstowcs