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.

Valor retornado

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 terminação seja encontrado, uma sequência multibyte que não corresponda 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 usar mbsrlen em vez de mbslen, se uma chamada subsequente para mbsrtowcs for usada em vez de mbstowcs.

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, ele será atribuído ao 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 foi interrompida.

Se o wcstr argumento for um ponteiro nulo, o argumento será ignorado count e mbsrtowcs retornará o 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âmetro 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, confira Estado global no CRT.

Exceções

A mbsrtowcs função é segura para multithread, 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

Confira também

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