mbstowcs, _mbstowcs_l

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

Convierte una secuencia de caracteres multibyte en una secuencia de caracteres anchos correspondiente. Existen versiones más seguras de estas funciones; 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
La dirección de una secuencia de caracteres anchos.

[in] mbstr
La dirección de una secuencia de null terminó caracteres multibyte.

[in] count
El número máximo de caracteres multibyte a convertir.

[in] locale
Configuración regional que se va a usar.

Si mbstowcs convierte correctamente la cadena de origen, devuelve el número de caracteres multibyte convertidos. Si el wcstr argumento es NULL, la función devuelve el tamaño necesario (en caracteres anchos) de la cadena de destino. Si mbstowcs encuentra un carácter multibyte no válido, devuelve -1. Si el valor devuelto es count, la cadena de caracteres anchos no está terminada en null.

System_CAPS_ICON_important.jpg Importante

Asegúrese de que wcstr y mbstr no se superponen, y de que count refleja correctamente el número de caracteres multibyte a convertir.

El mbstowcs función convierte hasta un máximo de count caracteres multibyte señalada por mbstr en una cadena de caracteres anchos correspondientes que vienen determinados por la configuración regional actual. Almacena la cadena de caracteres anchos resultante en la dirección representada por wcstr . El resultado es similar a una serie de llamadas a mbtowc. Si mbstowcs encuentra el carácter null de un solo byte ('\0') antes o al count se produce, convierte el carácter nulo en un carácter nulo de caracteres anchos (L '\0') y se detiene. Por tanto, la cadena de caracteres anchos en wcstr está terminada en null solo si se encuentra un carácter nulo durante la conversión. Si las secuencias señaladas por wcstr y mbstr se superponen, el comportamiento es indefinido.

Si el wcstr argumento es NULL, mbstowcs devuelve el número de caracteres anchos que resultaría de la conversión, sin incluir un carácter nulo de terminación. La cadena de origen debe ser terminada en null que devolverá el valor correcto. Si necesita la cadena de carácter ancho resultante sea terminada en null, agregue uno para el valor devuelto.

Si el mbstr argumento es NULL, o si count es > INT_MAX, se invoca el controlador de parámetros no válidos, como se describe en validación del parámetro . Si la ejecución puede continuar, errno se establece en EINVAL y la función devuelve -1.

mbstowcsutiliza la configuración regional actual para cualquier comportamiento dependiente de la configuración regional; _mbstowcs_l es idéntico, salvo que usa la configuración regional que se pasa en su lugar. Para obtener más información, vea Locale.

En C++, estas funciones tienen sobrecargas de plantilla que invocan los homólogos seguros más recientes de estas funciones. Para obtener más información, consulta Secure Template Overloads.

RutinaEncabezado necesario
mbstowcs<stdlib.h>
_mbstowcs_l<stdlib.h>

Para obtener información adicional de compatibilidad, vea Compatibilidad en la Introducción.

// 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  

No es aplicable. Para llamar a la función estándar de C, use PInvoke. Para obtener más información, vea Ejemplos de invocación de plataforma.

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres Multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar

Mostrar: