Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / C

mbrtowc — conversão multibyte reiniciável C23

`mbrtowc(pwc, s, n, ps)` de `<wchar.h>` examina no máximo `n` bytes do próximo caráter multibyte na codificação de execução atual. Ao completar um caráter válido devolve o número de bytes que o completaram e guarda o `wchar_t` correspondente se `pwc != NULL`; o `mbstate_t` apontado por `ps` continua um caráter dividido entre buffers.

Versão: C23

Sintaxe

size_t mbrtowc(wchar_t * restrict pwc, const char * restrict s, size_t n, mbstate_t * restrict ps);

mbrtowc(pwc, s, n, ps) de <wchar.h> examina no máximo n bytes do próximo caráter multibyte na codificação de execução atual. Ao completar um caráter válido devolve o número de bytes que o completaram e guarda o wchar_t correspondente se pwc != NULL; o mbstate_t apontado por ps continua um caráter dividido entre buffers.

O exemplo seleciona o locale garantido "C", inicializa explicitamente o estado a zero e converte realmente o "A" de um byte. A saída 1 0041 1 confirma um byte consumido, o valor do caráter largo e o regresso ao estado inicial indicado por mbsinit.

O resultado 0 indica caráter largo nulo e estado inicial, (size_t)-2 um caráter incompleto mas potencialmente válido sem escrita e (size_t)-1 erro com errno == EILSEQ, sem escrita e com estado não especificado. Após -2, fornece os bytes seguintes com o mesmo ps; após -1, reinicializa antes de continuar. s == NULL equivale exatamente a mbrtowc(NULL, "", 1, ps), ps == NULL usa estado interno sem garantia contra data races e wchar_t não tem de ser um ponto Unicode. Quando s == NULL, os valores pwc e n fornecidos pelo chamador são ignorados.

Exemplos

#include <locale.h>
#include <stdio.h>
#include <wchar.h>
int main(void){setlocale(LC_CTYPE,"C");mbstate_t state={0};wchar_t wc=0;size_t n=mbrtowc(&wc,"A",1,&state);printf("%zu %04lX %d\n",n,(unsigned long)wc,mbsinit(&state)!=0);return 0;}

Resultado

1 0041 1

O exemplo seleciona o locale garantido `"C"`, inicializa explicitamente o estado a zero e converte realmente o `"A"` de um byte. A saída `1 0041 1` confirma um byte consumido, o valor do caráter largo e o regresso ao estado inicial indicado por `mbsinit`.

Fontes