mbsrtowcs

Статья
06/09/2015

Преобразует строку многобайтовых символов в текущем языковом стандарте в соответствующую строку расширенных символов с возможностью перезапуска в середине многобайтового символа. Существует более безопасная версия этой функции, см. раздел mbsrtowcs_s.

size_t mbsrtowcs(    wchar_t *wcstr,    const char **mbstr,    sizeof count,    mbstate_t *mbstate ); template <size_t size> size_t mbsrtowcs(    wchar_t (&wcstr)[size],    const char **mbstr,    sizeof count,    mbstate_t *mbstate ); // C++ only

Параметры

[выходной] wcstr
Адрес для сохранения результирующей преобразованной строки расширенных символов.
[in, out] mbstr
Косвенный указатель на расположение преобразуемой строки многобайтовых символов.
[in] count
Максимальное число символов (не байтов) для преобразования и сохранения в wcstr.
[in, out] mbstate
Указатель на объект состояния преобразования mbstate_t. Если это значение является пустым указателем, используется статичный внутренний объект состояния преобразования. Так как внутренний объект mbstate_t не является потокобезопасным, мы рекомендуем всегда передавать собственный параметр mbstate.

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

Возвращает число успешно преобразованных символов без учета завершающего нуль-символа, если он есть. В случае ошибки возвращает (size_t)(-1) и устанавливает для errno значение EILSEQ.

Заметки

Функция mbsrtowcs преобразует строку многобайтовых символов, на которую косвенно указывает параметр mbstr, в расширенные символы, сохраняемые в буфере, на который указывает параметр wcstr. При этом используется состояние преобразования, содержащееся в mbstate. Преобразование продолжается для каждого символа до тех пор, пока не встретится завершающий многобайтовый нуль-символ, многобайтовая последовательность, не соответствующая допустимому символу в текущем языковом стандарте, или пока не будет преобразовано count симв. Если функция mbsrtowcs встречает многобайтовый нуль-символ ("\0") до или после count симв., она преобразовывает его в 16-разрядный завершающий нуль-символ и останавливается.

Таким образом, строка расширенных символов wcstr завершается нуль-символом только в том случае, если функция mbsrtowcs встречает многобайтовый нуль-символ во время преобразования. Если последовательности, на которые указывают параметры mbstr и wcstr, перекрываются, то поведение mbsrtowcs не определено. На функцию mbsrtowcs влияет категория LC_TYPE текущего языкового стандарта.

Функция mbsrtowcs отличается от функции mbstowcs, _mbstowcs_l возможностью перезапуска. Состояние преобразования хранится в переменной mbstate для последующих вызовов тех же или других перезапускаемых функций. При смешанном использовании перезапускаемых и неперезапускаемых функций результаты становятся неопределенными. Например, в приложении необходимо использовать функцию mbsrlen вместо функции mbslen, если в последующем вызове используется функция mbsrtowcs, а не функция mbstowcs..

Если wcstr не является пустым указателем, то объекту указателя, на который указывает параметр mbstr, присваивается пустой указатель, если преобразование останавливается из-за достижения завершающего нуль-символа. В противном случае ему назначается адрес позиции, следующей за последним преобразованным многобайтовым символом, если таковая имеется. Это позволяет продолжить преобразование с того же места при последующем вызове функции.

Если аргумент wcstr является пустым указателем, аргумент count игнорируется и mbsrtowcs возвращает необходимый размер конечной строки в расширенных символах. Если mbstate является пустым указателем, функция использует статичный внутренний объект состояния преобразования mbstate_t, не являющийся потокобезопасным. Если у последовательности символов mbstr нет соответствующего представления в виде многобайтовых символов, возвращается значение -1 и для errno устанавливается значение EILSEQ.

Если параметр mbstr представляет собой пустой указатель, вызывается обработчик недопустимого параметра, как описано в разделе Проверка параметров. Если продолжение выполнения разрешено, эта функции задает для errno значение EINVAL и возвращает -1.

В C++ эта функция имеет шаблонную перегрузку, которая вызывает более новые и безопасные аналоги этой функции. Для получения дополнительной информации см. Безопасные перегрузки шаблонов.

Исключения

Функция mbsrtowcs является потокобезопасной, если ни одна из функций в текущем потоке не вызывает setlocale, пока выполняется данная функция, и аргумент mbstate не является пустым указателем.