mbsrtowcs

Artigo
06/09/2015

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

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
Endereço para armazenar a cadeia de caracteres largos convertido resultante.
[in, out] mbstr
Ponteiro indireto para o local da cadeia de caracteres multibyte para converter.
[in] count
O número máximo de caracteres (não em bytes) para converter e armazenar em wcstr.
[in, out] mbstate
Um ponteiro para um mbstate_t objeto de estado de conversão. Se esse valor for um ponteiro nulo, um objeto de estado de conversão interna estático é usado. Porque o interno mbstate_t objeto não é thread-safe, recomendamos que você sempre passa seu próprio mbstate parâmetro.

Valor de retorno

Retorna o número de caracteres convertida com êxito, não incluindo o caractere de terminação nula, se houver. Retorna (size_t)(-1) se ocorreu um erro e define errno para EILSEQ.

Comentários

O mbsrtowcs função converte uma cadeia de caracteres multibyte indiretamente apontada 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é encontrar qualquer uma terminação nula caracteres multibyte, uma seqüência multibyte não corresponde a um caractere válido na localidade atual for encontrada, ou até count caracteres tiverem 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 pára.

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

O mbsrtowcs função difere da 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. 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 subsequente mbsrtowcs é usado em vez dembstowcs.

Se wcstr não é um ponteiro nulo, o objeto de ponteiro apontado por mbstr é atribuído um ponteiro nulo se a conversão foi interrompida porque foi atingido um caractere nulo de terminação. Caso contrário, ela é atribuída passado simplesmente endereço do último caractere multibyte convertido, se houver. Isso permite que uma chamada de função subsequentes reiniciar a conversão em que essa chamada é interrompido.

Se o wcstr argumento é um ponteiro nulo, o count argumento é ignorado e mbsrtowcs retorna o tamanho necessário em caracteres largos para a cadeia de caracteres de destino. Se mbstate é um ponteiro nulo, a função usa um estático thread safe interno mbstate_t objeto de estado de conversão. Se a seqüência de caracteres mbstr não tem um multibyte correspondente a representação de caracteres, -1 será retornado e o errno está definida como EILSEQ.

Se mbstr isa ponteiro nulo, o manipulador de parâmetro inválido é invocado, como descrito em Validação do parâmetro. Se a execução tiver permissão para continuar, essa função define errno como EINVAL e retorna -1.

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

Exceções

O mbsrtowcs função é safe multithread desde que nenhuma função no thread atual chama setlocale desde que essa função está em execução e o mbstate argumento não é um ponteiro nulo.