mbsrtowcs

Artigo
02/25/2013

Converte uma seqüência de caracteres multibyte em uma seqüência de caracteres de largura correspondente.Uma versão mais segura desta função está disponível. see mbsrtowcs.

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

[out]wcstr
O resultante convertido a localização de endereço da cadeia de caracteres largos.
[in]mbstr
Indiretamente aponta para o local da seqüência de caracteres multibyte a ser convertido.
[in]count
O número de caracteres a ser convertido.
[in]mbstate
Um ponteiro para um mbstate_t objeto de estado de conversão.

Valor de retorno

Retorna o número de palavras convertido com êxito, não incluindo o nulo de terminação nulo word (se houver), caso contrário -1 se ocorreu um erro.

Comentários

O mbsrtowcs função converte uma seqüência de caracteres multibyte, começando no estado de conversão especificada contido no mbstate, dos valores indiretos apontados na mbstr, no endereço de wcstr.A conversão continuará para cada caractere até: depois que um valor nulo de terminação caracteres multibyte for encontrado, quando um caractere correspondente não for encontrado ou quando o próximo caractere excede o limite contido no count.Se mbsrtowcs encontra o caractere nulo multibyte ('\0') antes ou quando count ocorre, ele converte para um valor nulo de 16 bits encerrando o caractere e pára.

Assim, a cadeia de caracteres largos em wcstr é terminada com nulo somente se mbsrtowcs encontra um caractere nulo de multibyte durante a conversão.Se as seqüências apontada por mbstr e wcstr se sobrepõem, o comportamento de mbsrtowcs é indefinido.mbsrtowcsé afetado pela categoria de LC_TYPE da localidade atual.

O mbsrtowcs função difere mbstowcs, _mbstowcs_l por sua capacidade de reinicialização.O estado de conversão é armazenado em mbstate para chamadas subseqüentes para o mesmo ou outras funções reinicializáveis.Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciável.Por exemplo, um aplicativo deve usar mbsrlen em vez de mbslen, se uma chamada subseqüente para mbsrtowcs onde usado em vez dembstowcs.

Se a wcstr argumento é NULL, mbsrtombs retorna o tamanho necessário em palavras da cadeia de caracteres de destino.Se mbstate for nulo, o interno mbstate_t estado de conversão é usado.Se a seqüência de caracteres wchar não tem um correspondente multibyte representação de caracteres, -1 é retornado e a errno for definido como EILSEQ.

Se mbstr é NULL, o manipulador de parâmetro inválido é invocado, conforme descrito em Validação de parâmetro.Se a execução terá permissão para continuar, essa função define errno para EINVAL e retorna -1.

No C++, essa função possui uma sobrecarga de modelo que invoca a contraparte segura, mais recente desta função.Para obter mais informações, consulte Proteger Overloads de modelo.

Exceções

O mbsrtowcs função é seguro com vários threads, desde que nenhuma função no segmento atual chama setlocale enquanto esta função está sendo executado e o mbstate não é nulo.