mbsrtowcs

Converte um caractere multibyte na localidade atual em uma cadeia de caracteres largos correspondente, com a capacidade de reiniciar no meio de um caractere multibyte. Uma versão mais segura dessa função está disponível, confira mbsrtowcs_s.

Sintaxe

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

Parâmetros

wcstr
Endereço para armazenar a cadeia de caracteres largos convertida resultante.

mbstr
O ponteiro indireto para o local da cadeia de caracteres multibyte a ser convertida.

count
O número máximo de caracteres (não bytes) para converter e armazenar em wcstr.

mbstate
Um ponteiro para um objeto do estado da conversão mbstate_t. Se esse valor for um ponteiro nulo, um objeto de estado de conversão interno estático será usado. Como o objeto interno mbstate_t não é thread-safe, recomendamos que você sempre passe seu próprio mbstate parâmetro.

Retornar valor

Retorna o número de caracteres convertidos com êxito, sem incluir o caractere nulo de terminação, se houver. Retorna (size_t)(-1) se ocorreu um erro e define errno como EILSEQ.

Comentários

A função mbsrtowcs converte uma cadeia de caracteres multibyte apontada indiretamente por mbstr em caracteres largos armazenados no buffer apontado por wcstr usando o estado de conversão contido em mbstate. A conversão continua para cada caractere até que um caractere multibyte nulo de encerramento seja encontrado, uma sequência multibyte que não corresponde a um caractere válido na localidade atual seja encontrada ou até count que os caracteres tenham sido convertidos. Se mbsrtowcs encontra o caractere nulo multibyte ('\0') antes ou quando count ocorre, ele converte em um caractere nulo de terminação 16 bits e para.

Dessa forma, a cadeia de caracteres largos em wcstr será terminada em nulo somente se mbsrtowcs encontrar um caractere nulo multibyte durante a conversão. Se as sequências apontadas por mbstr e por wcstr se sobrepuserem, o comportamento de mbsrtowcs será indefinido. mbsrtowcs é afetado LC_TYPE pela categoria da localidade atual.

A mbsrtowcs função difere de , _mbstowcs_l por sua capacidade de mbstowcsreinicialização. O estado da conversão é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo deve ser usado mbsrlen em vez de , se uma chamada subsequente para mbsrtowcs for usada em vez de mbslenmbstowcs.

Se wcstr não for um ponteiro nulo, o objeto de ponteiro apontado por mbstr receberá um ponteiro nulo se a conversão for interrompida porque um caractere nulo de terminação foi atingido. Caso contrário, será atribuído o endereço logo após o último caractere multibyte convertido, se houver. Ele permite que uma chamada de função subsequente reinicie a conversão onde essa chamada parou.

Se o argumento for um ponteiro nulo, o argumento será ignorado e mbsrtowcs retornará o wcstrcount tamanho necessário em caracteres largos para a cadeia de caracteres de destino. Se mbstate for um ponteiro nulo, a função usará um objeto de estado de conversão mbstate_t interna estática não thread-safe. Se a sequência mbstr de caracteres não tiver uma representação de caracteres multibyte correspondente, um -1 será retornado e errno definido como EILSEQ.

Se mbstr for um ponteiro nulo, o manipulador de parâmetros inválido será chamado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essa função definirá errno como EINVAL e retornará -1.

Em C++, essa função tem uma sobrecarga de modelo que invoca o equivalente mais recente e seguro dessa função. Para obter mais informações, consulte Sobrecargas de modelo seguras.

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

Exceções

A mbsrtowcs função é segura para vários threads, desde que nenhuma função nas chamadas setlocale de thread atuais, desde que essa função esteja em execução e o mbstate argumento não seja um ponteiro nulo.

Requisitos

Rotina	Cabeçalho necessário
mbsrtowcs	<wchar.h>

Confira também

Conversão de dados
Localidade
Interpretação de sequências de caracteres multibyte
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit