mbsrtowcs

 

Para obtener la documentación más reciente de Visual Studio 2017 RC, consulte Documentación de Visual Studio 2017 RC.

Convierte una cadena de caracteres multibyte en la configuración regional actual en una cadena de caracteres anchos correspondiente, con la capacidad de reinicio en medio de un carácter multibyte. Una versión más segura de esta función está disponible; consulte mbsrtowcs_s.

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

Parámetros

[out] wcstr
Dirección para almacenar la cadena de caracteres anchos convertida.

[in, out] mbstr
Puntero indirecto a la ubicación de la cadena de caracteres multibyte a convertir.

[in] count
Número máximo de caracteres (no bytes) a convertir y almacenar en wcstr.

[in, out] mbstate
Un puntero a un objeto mbstate_t de estado de la conversión. Si este valor es un puntero nulo, se utiliza un objeto de estado de la conversión interno estático. Dado que el objeto mbstate_t interno no es seguro para subprocesos, se recomienda pasar siempre su propio parámetro mbstate.

Devuelve el número de caracteres convertidos correctamente, sin incluir el carácter nulo de terminación, de haberlo. Devuelve (size_t)(-1) si se produce un error y establece errno a EILSEQ.

La función mbsrtowcs convierte una cadena de caracteres multibyte indirectamente señalada por mbstr en caracteres anchos almacenados en el búfer señalado por wcstr, utilizando el estado de conversión contenido en mbstate. La conversión continúa para cada carácter hasta que se encuentra un carácter multibyte nulo de terminación, se encuentra una secuencia multibyte que no se corresponde con un carácter válido en la configuración regional actual, o se convierten count caracteres. Si mbsrtowcs encuentra el carácter multibyte nulo ('\0') antes o al producirse count, lo convierte en un carácter nulo de terminación de 16 bits y se detiene.

Por tanto, la cadena de caracteres anchos en wcstr tiene terminación nula solo si mbsrtowcs encuentra un carácter multibyte nulo durante la conversión. Si las secuencias señaladas por mbstr y wcstr se superponen, el comportamiento de mbsrtowcs no está definido. mbsrtowcs se ve afectado por la categoría LC_TYPE de la configuración regional actual.

El mbsrtowcs función difiere de mbstowcs, _mbstowcs_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 debe utilizar mbsrlen en lugar de mbslen si se utiliza una llamada subsiguiente a mbsrtowcs en lugar de a mbstowcs.

Si wcstr no es un puntero nulo, al objeto de puntero señalado por mbstr se le asigna un puntero nulo si la conversión se detuvo por encontrarse un carácter nulo de terminación. De lo contrario, se le asigna la dirección inmediatamente posterior al último carácter multibyte convertido, de haberlo. Esto permite que una llamada de función subsiguiente reinicie la conversión en el punto en que se detuvo esta llamada.

Si el argumento wcstr es un puntero nulo, el argumento count se omite y mbsrtowcs devuelve el tamaño requerido en caracteres anchos para la cadena de destino. Si mbstate es un puntero nulo, la función usa un objeto de estado de la conversión mbstate_t interno estático, no seguro para subprocesos. Si la secuencia de caracteres mbstr no tiene una representación de caracteres multibyte correspondiente, se devuelve el valor -1 y errno se establece a EILSEQ.

Si mbstr se invoca un puntero nulo, el controlador de parámetros no válidos, como se describe en validación del parámetro. Si la ejecución puede continuar, esta función establece errno en EINVAL y devuelve -1.

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, consulta Secure Template Overloads.

La función mbsrtowcs es segura para subprocesos siempre y cuando ninguna función en el proceso actual llame a setlocale, mientras se ejecute esta función y el argumento mbstate no sea un puntero nulo.

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.

RutinaEncabezado necesario
mbsrtowcs<wchar.h>

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres Multibyte
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit

Mostrar: