Compartilhar via

mbstowcs_s, _mbstowcs_s_l

  • Artigo

Converte uma sequência de caracteres multibyte em uma sequência de caracteres largos correspondente. Versões do , com aprimoramentos de segurança, _mbstowcs_lconforme descrito em Recursos de segurança no CRT.mbstowcs

Sintaxe

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parâmetros

pReturnValue
O número de caracteres convertidos.

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

sizeInWords
O tamanho do buffer wcstr em palavras.

mbstr
O endereço de uma sequência de caracteres multibyte terminadas por nulo.

count
O número máximo de caracteres largos a serem armazenados no buffer wcstr, não incluindo o caractere nulo de terminação ou _TRUNCATE.

locale
A localidade a ser usada.

Valor retornado

Zero se for bem-sucedido ou um código de erro em caso de falha.

Condição de erro Valor retornado e errno
wcstr é NULL e sizeInWords> 0 EINVAL
mbstr é NULL EINVAL
O buffer de destino é muito pequeno para conter a cadeia de caracteres convertida (a menos que count seja _TRUNCATE; consulte Comentários abaixo) ERANGE
wcstr não é e NULL sizeInWords == 0 EINVAL

Se qualquer uma dessas condições ocorrer, a exceção de parâmetro inválido será invocada conforme descrito em Validação de parâmetro. Se a execução puder continuar, a função retornará um código de erro e definirá errno conforme indicado na tabela.

Comentários

A função mbstowcs_s converte uma cadeia de caracteres multibyte apontada por mbstr em caracteres largos armazenados no buffer apontado por wcstr. A conversão continuará para cada caractere até que uma das seguintes condições seja atendida:

  • Um caractere nulo multibyte é encontrado

  • Um caractere multibyte inválido é encontrado

  • O número de caracteres largos armazenados no buffer wcstr é igual a count.

A cadeia de caracteres de destino é sempre terminada em nulo (mesmo se houver um erro).

Se count for o valor especial _TRUNCATE, mbstowcs_s converterá o máximo da cadeia de caracteres que caberá no buffer de destino ainda deixando espaço para um terminador nulo.

Se mbstowcs_s converter com êxito a cadeia de caracteres de origem, ele colocará o tamanho em caracteres largos da cadeia de caracteres convertida, incluindo o terminador nulo, em *pReturnValue (provided pReturnValue isn't NULL). O tamanho é calculado mesmo se o wcstr argumento for NULL, e fornece uma maneira de determinar o tamanho do buffer necessário. Se wcstr for NULL, count é ignorado e sizeInWords deve ser 0.

Se mbstowcs_s encontrar um caractere multibyte inválido, ele colocará 0 em *pReturnValue, definirá o buffer de destino como uma cadeia de caracteres vazia, definirá errno como EILSEQe retornará EILSEQ.

Se as sequências apontadas por mbstr e por wcstr se sobrepuserem, o comportamento de mbstowcs_s será indefinido.

Importante

Verifique se wcstr e mbstr não se sobrepõem e se count reflete corretamente o número de caracteres multibyte a ser convertido.

mbstowcs_s usa a localidade atual de qualquer comportamento dependente da localidade; _mbstowcs_s_l é idêntico, exceto pelo fato de que ele usa a localidade passada. Para obter mais informações, consulte Localidade.

Em C++, o uso dessas funções é simplificado pelas sobrecargas de modelo; as sobrecargas podem inferir o tamanho do buffer automaticamente (eliminando a necessidade de especificar um argumento de tamanho) e podem substituir automaticamente funções mais antigas e não seguras por suas equivalentes mais recentes e seguras. 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.

Requisitos

Rotina Cabeçalho necessário
mbstowcs_s <stdlib.h>
_mbstowcs_s_l <stdlib.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Confira também

Conversão de dados
Localidade
MultiByteToWideChar
Interpretação de sequências de caracteres multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l