mbstowcs, _mbstowcs_l
Converte uma seqüência de caracteres multibyte em uma seqüência correspondente de caracteres de largura.Versões mais seguras dessas funções estão disponíveis; see mbstowcs_s, _mbstowcs_s_l.
size_t mbstowcs(
wchar_t *wcstr,
const char *mbstr,
size_t count
);
size_t _mbstowcs_l(
wchar_t *wcstr,
const char *mbstr,
size_t count,
_locale_t locale
);
template <size_t size>
size_t mbstowcs(
wchar_t (&wcstr)[size],
const char *mbstr,
size_t count
); // C++ only
template <size_t size>
size_t _mbstowcs_l(
wchar_t (&wcstr)[size],
const char *mbstr,
size_t count,
_locale_t locale
); // C++ only
Parâmetros
[out]wcstr
O endereço de uma seqüência de caracteres de largura.[in]mbstr
O endereço de uma seqüência de null finalizada caracteres multibyte.[in]count
O número máximo de caracteres multibyte para converter.[in]locale
A localidade para usar.
Valor de retorno
Se mbstowcs com êxito, converte a seqüência de origem, ele retorna o número de caracteres multibyte convertidos.Se a wcstr argumento é NULL, a função retorna o tamanho necessário (em caracteres de largura) da seqüência de caracteres de destino.Se mbstowcs encontra um caractere inválido multibyte, ele retorna – 1.Se o valor de retorno é count, a seqüência de caracteres largos não é terminada por caractere nulo.
Observação de segurança |
---|
Certifique-se de que wcstr e mbstr não se sobrepõem e que count corretamente reflete o número de caracteres multibyte para converter. |
Comentários
O mbstowcs função converte um número máximo de count caracteres multibyte apontada por mbstr para uma seqüência de caracteres de largura correspondentes que são determinadas pela localidade do atual.Ele armazena a seqüência de caracteres largos resultante no endereço representado por wcstr*.* O resultado é semelhante a uma série de chamadas para mbtowc.Se mbstowcs encontra o caractere de um byte nulo ('\0') antes ou quando count ocorre, ele converte o caractere nulo para um caractere nulo de caractere largo ('\0' L) e pára.Assim, a cadeia de caracteres largos em wcstr é terminada com nulo somente se um caractere nulo é encontrado durante a conversão.Se as seqüências apontada por wcstr e mbstr se sobrepõem, o comportamento é indefinido.
Se a wcstr argumento é NULL, mbstowcs retorna o número de caracteres extensos causada pela conversão, não incluindo um terminador nulo.A seqüência de origem deve ser terminada com nulo para o valor correto a ser retornado.Se você precisar que a seqüência de caracteres largos resultante ser terminada por caractere nulo, adicione um ao valor retornado.
If the mbstr argument is NULL, or if count is > INT_MAX, 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, errno é definido como EINVAL e a função retornará -1.
mbstowcsusa a localidade atual para qualquer comportamento depende da localidade; _mbstowcs_l é idêntica, exceto que ele usa a localidade passada em vez disso.Para obter mais informações, consulte Localidade.
No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.Para obter mais informações, consulte Proteger Overloads de modelo.
Requisitos
Rotina |
Cabeçalho necessário |
---|---|
mbstowcs |
<stdlib.h> |
_mbstowcs_l |
<stdlib.h> |
Para obter informações adicionais de compatibilidade, consulte compatibilidade na introdução.
Exemplo
// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function
#include <stdlib.h>
#include <stdio.h>
#include <locale.h>
int main( void )
{
size_t size;
int nChar = 2; // number of characters to convert
int requiredSize;
unsigned char *pmbnull = NULL;
unsigned char *pmbhello = NULL;
char* localeInfo;
wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
wchar_t *pwc;
/* Enable the Japanese locale and codepage */
localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
printf("Locale information set to %s\n", localeInfo);
printf( "Convert to multibyte string:\n" );
requiredSize = wcstombs( NULL, pwchello, 0); // C4996
// Note: wcstombs is deprecated; consider using wcstombs_s
printf(" Required Size: %d\n", requiredSize);
/* Add one to leave room for the null terminator. */
pmbhello = (unsigned char *)malloc( requiredSize + 1);
if (! pmbhello)
{
printf("Memory allocation failure.\n");
return 1;
}
size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
// Note: wcstombs is deprecated; consider using wcstombs_s
if (size == (size_t) (-1))
{
printf("Couldn't convert string. Code page 932 may"
" not be available.\n");
return 1;
}
printf( " Number of bytes written to multibyte string: %u\n",
(unsigned int) size );
printf( " Hex values of the " );
printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
printf( " Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");
printf( "Convert back to wide-character string:\n" );
/* Assume we don't know the length of the multibyte string.
Get the required size in characters, and allocate enough space. */
requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
/* Add one to leave room for the NULL terminator */
pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
if (! pwc)
{
printf("Memory allocation failure.\n");
return 1;
}
size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
if (size == (size_t) (-1))
{
printf("Couldn't convert string--invalid multibyte character.\n");
}
printf( " Characters converted: %u\n", (unsigned int)size );
printf( " Hex value of first 2" );
printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
free(pwc);
free(pmbhello);
}
Equivalência do .NET Framework
Não aplicável. Para chamar a função c padrão, use PInvoke. Para obter mais informações, consulte Exemplos de invocação de plataforma.