wcstombs, _wcstombs_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 anchos a una secuencia de caracteres multibyte correspondiente. Existen versiones más seguras de estas funciones; consulte wcstombs_s, _wcstombs_s_l.

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
La dirección de una secuencia de caracteres multibyte.

wcstr
La dirección de una secuencia de caracteres anchos.

count
El 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.

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 existe). Si el mbstr argumento es NULL, wcstombs devuelve el tamaño en bytes de la cadena de destino. Si wcstombs encuentra un carácter ancho no se puede convertir en un carácter multibyte, devuelve –&1; convertido al tipo size_t y establece errno a EILSEQ.

El wcstombs función convierte la cadena de caracteres anchos señalada wcstr a los caracteres de la multibyte correspondiente y almacena los resultados en el mbstr matriz. El count parámetro 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 será necesario al convertir una cadena de caracteres anchos. Algunos caracteres anchos requerirá sólo un byte de la cadena de salida; otras requieren dos. Si hay dos bytes en la cadena de salida de varios bytes para cada carácter ancho de la cadena de entrada (incluido el carácter ancho NULL), se garantiza que el resultado para ajustarse.

Si wcstombs encuentra el carácter null de caracteres anchos (L '\0') antes o al count se produce, lo convierte en un 0 de 8 bits y se detiene. Por lo tanto, la cadena de caracteres multibyte en mbstr está terminada en null solo si wcstombs encuentra un carácter nulo 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 mbstr argumento es NULL, wcstombs devuelve el tamaño en bytes de la cadena de destino.

wcstombs valida sus parámetros. Si wcstr es NULL, o si count es mayor queINT_MAX, esta función invoca el controlador de parámetros no válidos, como se describe en validación del parámetro . Si la ejecución puede continuar, la función establece errno a EINVAL y devuelve -1.

wcstombsutiliza la configuración regional actual para cualquier comportamiento dependiente de la configuración regional; _wcstombs_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
wcstombs<stdlib.h>
_wcstombs_l<stdlib.h>

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

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

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

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
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte

Mostrar: