mbrtoc16, mbrtoc32

Converte o primeiro caractere multibyte UTF-8 de uma cadeia de caracteres no caractere UTF-16 ou UTF-32 equivalente.

Sintaxe

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
);

Parâmetros

destination
O ponteiro para o char16_t ou char32_t equivalente do caractere multibyte UTF-8 a ser convertido. Se for null, a função não armazenará um valor.

source
O ponteiro para a cadeia de caracteres multibyte UTF-8 a ser convertida.

max_bytes
O número máximo de bytes em source a serem examinados para um caractere a ser convertido. Esse argumento deve ser um valor entre um e o número de bytes, incluindo qualquer terminador nulo, restante em source.

state
Ponteiro para um objeto de mbstate_t estado de conversão usado para interpretar a cadeia de caracteres multibyte UTF-8 para um ou mais caracteres de saída.

Valor retornado

Em caso de sucesso, retorna o valor da primeira dessas condições que se aplica, dado o valor state atual:

Valor	Condição
0	Os próximos max_bytes ou menos caracteres convertidos correspondem source ao caractere largo nulo, que é o valor armazenado se destination não for nulo. state contém o estado de deslocamento inicial.
Entre 1 e max_bytes, inclusive	O valor retornado é o número de bytes de source que completa um caractere multibyte válido. O caractere largo convertido será armazenado se destination não for nulo.
-3	O próximo caractere largo resultante de uma chamada anterior para a função foi armazenado em destination if destination não é nulo. Nenhum byte de source é consumido por essa chamada para a função. Quando source aponta para um caractere multibyte UTF-8 que requer mais de um caractere largo para representar (por exemplo, um par substituto), o state valor é atualizado para que a próxima chamada de função grave o caractere extra.
-2	Os próximos max_bytes bytes representam um caractere multibyte UTF-8 incompleto, mas potencialmente válido. Não é armazenado nenhum valor em destination. Esse resultado poderá ocorrer se max_bytes for zero.
-1	Ocorreu um erro de codificação. Os bytes seguintes max_bytes ou inferiores não contribuem para um caractere multibyte UTF-8 completo e válido. Não é armazenado nenhum valor em destination. EILSEQ é armazenado e errno o valor state do estado de conversão não é especificado.

Comentários

A mbrtoc16 função lê até max_bytes bytes para source localizar o primeiro caractere multibyte UTF-8 completo e válido e, em seguida, armazena o caractere UTF-16 equivalente em destination. Se o caractere exigir mais de um caractere de saída UTF-16, como um par substituto, o state valor será definido para armazenar o próximo caractere UTF-16 na destination próxima chamada para mbrtoc16. A função mbrtoc32 é idêntica, mas a saída é armazenada como um caractere UTF-32.

Se source for nulo, essas funções retornarão o equivalente a uma chamada feita usando argumentos de for destination, "" (uma cadeia de NULL caracteres vazia terminada em nulo) para source, e 1 para max_bytes. Os valores passados de destination e max_bytes são ignorados.

Se source não for nulo, a função começará no início da cadeia de caracteres e inspecionará até max_bytes bytes para determinar o número de bytes necessários para concluir o próximo caractere multibyte UTF-8, incluindo quaisquer sequências de deslocamento. Se os bytes examinados contiverem um caractere multibyte UTF-8 válido e completo, a função converterá o caractere no caractere ou caracteres largos de 16 bits ou 32 bits equivalentes. Se destination não for nulo, a função armazenará o primeiro (e possivelmente único) caractere de resultado no destino. Se forem necessários caracteres de saída extras, um valor será definido em state, para que as chamadas subsequentes para a função gerem os caracteres extras e retornem o valor -3. Se não for necessário mais nenhum caractere de saída adicional, state será definido para o estado de deslocamento inicial.

Para converter caracteres multibyte não UTF-8 em caracteres LE UTF-16, use as mbrtowcfunções , mbtowc ou _mbtowc_l .

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Requisitos

Função	Cabeçalho C	Cabeçalho C++
mbrtoc16, mbrtoc32	<uchar.h>	<cuchar>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s