Поделиться через

mbrtoc16, mbrtoc32

  • Статья

Преобразует первый многобайтовый символ UTF-8 в строке в эквивалентный символ в кодировке UTF-16 или UTF-32.

Синтаксис

size_t mbrtoc16(
   char16_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

size_t mbrtoc32(
   char32_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

Параметры

destination
Указатель на эквивалент char16_t или char32_t многобайтового символа UTF-8, который нужно преобразовать. Если значение равно NULL, функция не сохраняет значение.

source
Указатель на строку многобайтовых символов UTF-8, которую нужно преобразовать.

max_bytes
Максимальное число байтов в source , которое нужно проанализировать на наличие символа для преобразования. Этот аргумент должен быть значением между одним и числом байтов, включая любой терминатор null, оставшийся в source.

state
Указатель на объект состояния преобразования, используемый для интерпретации многобайтовой mbstate_t строки UTF-8 на один или несколько выходных символов.

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

В случае успешного выполнения возвращает значение, соответствующее первому из приведенных ниже условий, с учетом текущего значения state .

Значение Condition
0 max_bytes Следующие или меньше символов, преобразованных из source соответствующих широкому символу NULL, которое хранится, если destination значение не равно NULL.

state содержит начальное состояние сдвига.
От 1 до max_bytesвключительно Возвращаемое значение равно количеству байтов в source , составляющих допустимый многобайтовый символ. Преобразованный широкий символ хранится, если destination не имеет значения NULL.
-3 Следующий широкий символ, полученный из предыдущего вызова функции, был сохранен, destination если destination не имеет значения NULL. Байты из source не используются при этом вызове функции.

Если source указывает на многобайтовый символ UTF-8, для которого требуется несколько расширенных символов для представления (например, суррогатная пара), state то значение обновляется таким образом, чтобы следующий вызов функции записывает дополнительный символ.
-2 Следующие max_bytes байты представляют неполный, но потенциально допустимый многобайтовый символ UTF-8. Значение в destinationне сохраняется. Этот результат может быть получен, если max_bytes равно нулю.
-1 Произошла ошибка кодирования. Следующие max_bytes или меньше байтов не вносят свой вклад в полный и допустимый многобайтовый символ UTF-8. Значение в destinationне сохраняется.

EILSEQ хранится и errno значение state состояния преобразования не указано.

Замечания

Функция mbrtoc16 считывает до max_bytes байтов, source чтобы найти первый полный, допустимый многобайтовый символ UTF-8, а затем сохраняет эквивалентный символ UTF-16 в destination. Если для символа требуется несколько выходных символов UTF-16, например суррогатная пара, state то для хранения следующего символа UTF-16 в destination следующем вызове mbrtoc16. Функция mbrtoc32 идентична, но выходные данные сохраняются в виде символа в формате UTF-32.

Если source значение null, эти функции возвращают эквивалент вызова, выполненного с использованием аргументов NULL для destinationsource, "" (пустая, пустая строка, завершаемая значением NULL) и 1 для max_bytes. Значения, передаваемые в параметрах destination и max_bytes , игнорируются.

Если source значение не равно null, функция начинается в начале строки и проверяет до max_bytes байтов, чтобы определить количество байтов, необходимых для выполнения следующего многобайтового символа UTF-8, включая все последовательности смен. Если проверяемые байты содержат допустимый и полный многобайтовый символ UTF-8, функция преобразует его в эквивалентный 16- или 32-битовый расширенный символ (либо несколько символов). Если destination значение не равно NULL, функция сохраняет первый (и, возможно, только) символ результата в назначении. Если требуются дополнительные выходные символы, значение задается stateтаким образом, чтобы последующие вызовы функции выводили дополнительные символы и возвращали значение -3. Если дополнительных символов больше не требуется, state устанавливается в начальное состояние сдвига.

Чтобы преобразовать многобайтовые символы, отличные от UTF-8, в символы LE UTF-16, используйте mbrtowcфункции , mbtowc или _mbtowc_l .

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Требования

Function Заголовок C Заголовок C++
mbrtoc16, mbrtoc32 <uchar.h> <cuchar>

Дополнительные сведения о совместимости см. в разделе Совместимость.

См. также

Преобразование данных
Локаль
Интерпретация последовательностей многобайтовых символов
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s