Compartir a través de


mbstowcs, _mbstowcs_l

Convierte una secuencia de caracteres multibyte en una secuencia correspondiente de caracteres anchos. Hay disponibles versiones más seguras de estas funciones; vea 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 finalizó caracteres multibyte.

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

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

Valor devuelto

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

Nota de seguridadNota sobre la seguridad

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

Comentarios

La función de mbstowcs convierte hasta un número máximo de caracteres multibyte de count indicada por mbstr en una cadena de caracteres anchos correspondientes que están determinados por la configuración regional actual. Almacena la cadena de caracteres 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 solo- byte (“\0”) o antes o cuando count aparece, convierte el carácter null a un carácter null de caracteres anchos (L'\0) y se detiene. Así la cadena de caracteres en wcstr terminado en null solo si un carácter null se encuentra durante la conversión. Si las secuencias designadas por a wcstr y la superposición de mbstr , el comportamiento no están definidas.

Si el argumento de wcstr es NULL, mbstowcs devuelve el número de caracteres anchos que resultarían de conversión, sin incluir un carácter null final. La cadena de origen debe ser terminado en null para el valor correcto que se devolverá. Si necesita la cadena de caracteres anchos resultante hacer en null, agregue uno al valor devuelto.

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

mbstowcs utiliza la configuración regional actual para cualquier comportamiento configuración regional-dependiente; _mbstowcs_l es idéntico pero utiliza la configuración regional pasado en su lugar. Para obtener más información, vea Configuración regional.

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, vea Sobrecargas de plantilla seguras.

Requisitos

Rutina

Encabezado necesario

mbstowcs

<stdlib.h>

_mbstowcs_l

<stdlib.h>

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

Ejemplo

// 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);
}
  

Equivalente en .NET Framework

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.

Vea también

Referencia

Conversión de datos

Configuración regional

Interpretación de secuencias de caracteres de varios bytes

_mbclen, mblen, _mblen_l

mbtowc, _mbtowc_l

wcstombs, _wcstombs_l

wctomb, _wctomb_l

MultiByteToWideChar