wcrtomb

Convierte un carácter ancho en su representación de carácter multibyte. Hay disponible una versión más segura de esta función; consulte wcrtomb_s.

Sintaxis

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

Parámetros

mbchar
Carácter convertido multibyte resultante.

wchar
Carácter ancho que se va a convertir.

mbstate
Puntero a un objeto mbstate_t .

Valor devuelto

Devuelve el número de bytes necesarios para representar el carácter multibyte convertido; si se produce un error, devuelve -1.

Comentarios

La función wcrtomb convierte un carácter ancho, a partir del estado de conversión especificado incluido en mbstate, del valor incluido en wchar, en la dirección representada por mbchar. El valor devuelto es el número de bytes necesarios para representar el carácter multibyte correspondiente, pero no devolverá más de MB_CUR_MAX bytes.

Si mbstate es nulo, se usa el objeto interno mbstate_t que contiene el estado de conversión de mbchar. Si la secuencia wchar de caracteres no tiene una representación de caracteres multibyte correspondiente, se devuelve -1 y se establece EILSEQen errno .

La wcrtomb función difiere de wctomb, _wctomb_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.

En C++, esta función tiene una sobrecarga de plantilla que invoca a un homólogo más reciente y seguro de esta función. Para obtener más información, consulte Sobrecargas de plantilla 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 función wcrtomb es segura para subprocesos siempre y cuando ninguna función del proceso actual llame a setlocale mientras se ejecuta esta función y mbstate sea nulo.

Ejemplo

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}

The corresponding wide character "Q" was converted to the "Q" multibyte character.

Requisitos

Routine	Encabezado necesario
wcrtomb	<wchar.h>

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres de varios bytes
mbsinit