wcrtomb_s
Convierte un carácter ancho en su representación de carácter multibyte. Una versión de wcrtomb
con mejoras de seguridad, como se describe en Características de seguridad en CRT.
Sintaxis
errno_t wcrtomb_s(
size_t *pReturnValue,
char *mbchar,
size_t sizeOfmbchar,
wchar_t *wchar,
mbstate_t *mbstate
);
template <size_t size>
errno_t wcrtomb_s(
size_t *pReturnValue,
char (&mbchar)[size],
wchar_t *wchar,
mbstate_t *mbstate
); // C++ only
Parámetros
pReturnValue
Devuelve el número de bytes escritos o -1 si se ha producido un error.
mbchar
Carácter convertido multibyte resultante.
sizeOfmbchar
Tamaño de la variable mbchar
en bytes.
wchar
Carácter ancho que se va a convertir.
mbstate
Puntero a un objeto mbstate_t
.
Valor devuelto
Devuelve cero o un valor errno
si se produce un error.
Comentarios
La función wcrtomb_s
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 pReturnValue
será el número de bytes convertidos, pero no más de MB_CUR_MAX
bytes, o -1 si se ha producido un error.
Si mbstate
es nulo, se usa el estado de conversión interno mbstate_t
. Si el carácter contenido en wchar
no tiene un carácter multibyte correspondiente, el valor de pReturnValue
es -1 y la función devuelve el errno
valor de EILSEQ
.
La wcrtomb_s
función difiere de wctomb_s
, _wctomb_s_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 wcslen
si se empleara una llamada subsiguiente a wcsrtombs_s
en lugar de a wcstombs_s
.
En C++, el uso de esta función se simplifica con las sobrecargas de plantilla; las sobrecargas pueden deducir automáticamente la longitud de búfer (lo que elimina el requisito de especificar un argumento de tamaño) y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. 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_s
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_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//
#include <string.h>
#include <stdio.h>
#include <wchar.h>
int main( void )
{
errno_t returnValue;
size_t pReturnValue;
mbstate_t mbstate;
size_t sizeOfmbStr = 1;
char mbchar = 0;
wchar_t* wchar = L"Q\0";
// Reset to initial conversion state
memset(&mbstate, 0, sizeof(mbstate));
returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
*wchar, &mbstate);
if (returnValue == 0) {
printf("The corresponding wide character \"");
wprintf(L"%s\"", wchar);
printf(" was converted to a the \"%c\" ", mbchar);
printf("multibyte character.\n");
}
else
{
printf("No corresponding multibyte character "
"was found.\n");
}
}
The corresponding wide character "Q" was converted to a the "Q" multibyte character.
Requisitos
Routine | Encabezado necesario |
---|---|
wcrtomb_s |
<wchar.h> |
Consulte también
Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres de varios bytes
mbsinit