wcstombs, _wcstombs_l

Convierte una secuencia de caracteres anchos en una secuencia correspondiente de caracteres multibyte. Hay disponibles versiones más seguras de estas funciones; consulte wcstombs_s, _wcstombs_s_l.

Sintaxis

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parámetros

mbstr
Dirección de una secuencia de caracteres multibyte.

wcstr
Dirección de una secuencia de caracteres anchos.

count
Número máximo de bytes que se pueden almacenar en la cadena de salida multibyte.

locale
Configuración regional que se va a usar.

Valor devuelto

Si wcstombs convierte correctamente la cadena multibyte, devuelve el número de bytes escritos en la cadena de salida multibyte, sin incluir el carácter final NULL (si lo hubiera). Si el argumento mbstr es NULL, wcstombs devuelve el tamaño necesario en bytes de la cadena de destino. Si wcstombs encuentra un carácter ancho que no puede convertir en un carácter multibyte, devuelve -1 conversión al tipo size_t y establece en errnoEILSEQ.

Comentarios

La función wcstombs convierte la cadena de caracteres anchos a la que apunta wcstr en los caracteres multibyte correspondientes y almacena los resultados en la matriz mbstr. El parámetro count indica el número máximo de bytes que se pueden almacenar en la cadena de salida multibyte (es decir, el tamaño de mbstr). En general, no se conoce el número de bytes que se necesitarán al convertir una cadena de caracteres anchos. Algunos caracteres anchos solo requerirán un solo byte en la cadena de salida; otros requieren 2 bytes. Si hay 2 bytes en la cadena de salida multibyte para cada carácter ancho de la cadena de entrada (incluido el carácter NULLancho), se garantiza que el resultado se ajuste.

A partir de Windows 10 versión 1803 (10.0.17134.0), el tiempo de ejecución de C universal admite el uso de páginas con codificación UTF-8. Use wcstombs(NULL, wcstr, 0) para obtener el tamaño correcto que necesitará para la conversión, ya que suponiendo que necesitará dos bytes para cada carácter ancho puede no ser suficiente. Para obtener más información sobre la compatibilidad con UTF-8, consulte Compatibilidad con UTF-8.

Si wcstombs encuentra el carácter NULL de caracteres anchos (L'\0') mientras se produce count o antes, lo convierte en un 0 de 8 bits y se detiene. Por tanto, la cadena de caracteres multibyte en mbstr se terminal en NULL solo si wcstombs encuentra un carácter NULL de caracteres anchos durante la conversión. Si las secuencias señaladas por wcstr y mbstr se superponen, el comportamiento de wcstombs no está definido.

Si el argumento mbstr es NULL, wcstombs devuelve el tamaño necesario en bytes de la cadena de destino.

wcstombs valida sus parámetros. Si wcstr es , o si count es NULLmayor que INT_MAX, esta función invoca al controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, la función establece errno en EINVAL y devuelve -1.

wcstombs usa la configuración regional actual para cualquier comportamiento dependiente de la configuración regional; _wcstombs_l es igual, salvo que en su lugar usa la configuración regional pasada. 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, consulte Sobrecargas de plantillas seguras.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Requisitos

Routine	Encabezado necesario
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

Este programa muestra el comportamiento de la función wcstombs.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

Consulte también

Conversión de datos
Configuración regional
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte