wcsrtombs

Convierte una cadena de caracteres anchos en su representación de cadena de caracteres multibyte. Hay disponible una versión más segura de esta función; consulte wcsrtombs_s.

Sintaxis

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parámetros

mbstr
Ubicación de la dirección de la cadena de caracteres multibyte convertida resultante.

wcstr
Indirectamente apunta a la ubicación de la cadena de caracteres anchos que se va a convertir.

count
Número de caracteres que se van a convertir.

mbstate
Un puntero a un objeto mbstate_t de estado de la conversión.

Valor devuelto

Devuelve el número de bytes convertidos correctamente, sin incluir el byte nulo de finalización (si lo hubiera), de lo contrario, -1 si se ha producido un error.

Comentarios

La función wcsrtombs convierte una cadena de caracteres anchos, a partir del estado de conversión especificado incluido en mbstate, de los valores a los que se apunta indirectamente en wcstr, en la dirección de mbstr. La conversión continuará para cada carácter hasta que: se encuentre un carácter ancho de finalización nulo, se encuentre un carácter no correspondiente o el siguiente carácter supere el límite incluido en count. Si wcsrtombs encuentra el carácter nulo ancho (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 tiene un carácter de fin nulo solo si wcsrtombs encuentra un carácter ancho nulo durante la conversión. Si las secuencias señaladas por wcstr y mbstr se superponen, el comportamiento de wcsrtombs no está definido. wcsrtombs se ve afectado por la categoría LC_TYPE de la configuración regional actual.

La wcsrtombs función difiere de wcstombs, _wcstombs_l por su capacidad de reinicio. El estado de la conversión se almacena en mbstate para llamadas posteriores a la misma o a otras funciones reiniciables. Los resultados no están definidos cuando se combina el uso de funciones reiniciables y no reiniciables. Por ejemplo, una aplicación usaría wcsrlen en lugar de wcsnlen si se empleara una llamada subsiguiente a wcsrtombs en lugar de a wcstombs.

Si el argumento mbstr es NULL, wcsrtombs devuelve el tamaño necesario en bytes de la cadena de destino. Si mbstate es nulo, se usa el estado de conversión interno mbstate_t. Si la secuencia wchar de caracteres no tiene una representación de caracteres multibyte correspondiente, se devuelve -1 y se establece EILSEQen errno .

En C++, esta función tiene una sobrecarga de plantilla que invoca una contrapartida más nueva y segura de la función. 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.

Excepciones

La wcsrtombs función es segura multiproceso siempre y cuando no haya ninguna función en las llamadas de subproceso setlocale actuales mientras se ejecuta esta función y no mbstate es null.

Ejemplo

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

Requisitos

Routine	Encabezado necesario
wcsrtombs	<wchar.h>

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit