MBSTOWCS(3)

НАЗВАНИЕ
mbstowcs - преобразует многобайтовую строку в строку широких символов

СИНТАКСИС
#include <stdlib.h>

size_t mbstowcs(wchar_t *dest, const char *src, size_t n);

ОПИСАНИЕ
Если dest не является NULL-указателем, то функция mbstowcs преобразует многобайтовую строку *src в строку широких символов, начиная с dest. Максимум n широких символов запишутся в dest. Преобразование начинается с первичного состояния. Преобразование может остановиться по трем следующим причинам:

1. Была встречена неправильная многобайтовая последовательность. В этом случае возвращается (size_t)(-1).

2. Было сохранено n "непустых" широких символов в dest. В этом случае возвращается количество широких символов, записанных в dest, но при этом теряется статус смещения на это место.

3. Многобайтовая строка была полностью преобразована, включая завершающий '\0'. В этом случае возвращается количество широких символов, записанных в dest, за исключением завершающего символа L'\0'.

Программист должен убедиться, что в dest существует достаточно места для размещения хотя бы n широких символов.

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

Во избежание второго случая, описанного выше, программист должен убедиться, что n больше mbstowcs(NULL,src,0)+1 или равно ему.

ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
Функция mbstowcs возвращает количество широких символов, которые составляют преобразованную часть строки широких символов, но не содержат заключительный широкий null-символ. Если была встречена неправильная многобайтовая последовательность, то возвращается (size_t)(-1).

СООТВЕТСТВИЕ СТАНДАРТАМ
ISO/ANSI C, UNIX98

СМ. ТАКЖЕ
mbsrtowcs(3)

ЗАМЕЧАНИЯ
Поведение mbstowcs зависит от категории LC_CTYPE текущей локали.

Функция mbsrtowcs обеспечивает пользователя более удобным интерфейсом при тех же функциональных возможностях.