mbstowcs, _mbstowcs_l

Artigo
08/25/2010

Converte uma sequência de caracteres multibyte em uma sequência correspondente de caracteres largos.Versões mais seguras dessas funções estão disponível; consulte 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 sequência de caracteres largos.
[in] mbstr
O endereço de uma sequência de nulo finalizada caracteres multibyte.
[in]count
O número máximo de caracteres multibyte para converter.
[in]locale
A localidade para usar.

Valor de retorno

If mbstowcs com êxito converte a seqüência de caracteres de fonte, ela retorna o número de caracteres multibyte convertidos. Se o wcstr o argumento é NULL, a função retorna o dimensionar necessário (em caracteres largos) da seqüência de caracteres de destino. If mbstowcs encontrar um caractere inválido multibyte, retornará – 1. Se o valor retornado for 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 reflete o número de caracteres multibyte para converter corretamente.

Comentários

The mbstowcs função converte um número máximo de count caracteres de multibyte apontadas por mbstr para uma seqüência de caracteres largos correspondentes que são determinadas pela localidade corrente. Ele armazena a seqüência de caractere largos resultante no endereço representado por wcstr*.* O resultado é semelhante a uma série de chamadas para mbtowc. If mbstowcs encontra o caractere nulo de byte único ('\0') antes ou quando count ocorre, ele converte o caractere nulo de um caractere nulo de caractere largo (L '\0') e pára. Assim, a seqüência de caracteres de todo o 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 o wcstr o argumento é NULL, mbstowcs Retorna o número de caracteres largos que possam resultar de conversão, não incluindo um terminador nulo. A cadeia de caracteres de fonte deve ser terminada por caractere nulo para o valor correto a ser retornado.Se você precisar a seqüência de caracteres largos resultante ser terminada por caractere nulo, adicione um ao valor retornado.

Se o mbstr o argumento é NULL, ou se counté > INT_MAX, o manipulador de parâmetro inválido é chamado, 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.

mbstowcs usa a localidade corrente para qualquer comportamento dependente de localidade; _mbstowcs_l é idêntico, exceto pelo fato de que ele usa a localidade do passado em vez disso. For more information, see Localidade.

No C++, essas funções têm sobrecargas de modelo que invocam as suas similares do mais recentes, seguras dessas funções.For more information, see Proteger overloads de modelo.

Requisitos

Rotina	Cabeçalho necessário
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

Para obter informações adicionais 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);
}

Locale information set to Japanese_Japan.932 Convert to multibyte string:   Required Size: 4   Number of bytes written to multibyte string: 4   Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1   Codepage 932 uses 0x81 to 0x9f as lead bytes.  Convert back to wide-character string:   Characters converted: 2   Hex value of first 2 wide characters: 0x3042 0x3043