mbsrtowcs

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. Hay disponible una versión más segura de esta función; consulte mbsrtowcs_s.

Sintaxis

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

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

mbstr
Puntero indirecto a la ubicación de la cadena de caracteres multibyte a convertir.

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

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 interno mbstate_t no es seguro para subprocesos, se recomienda pasar siempre su propio mbstate parámetro.

Valor devuelto

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 produjo un error y establece en errno EILSEQ.

Comentarios

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, una secuencia multibyte que no se corresponde con un carácter válido en la configuración regional actual o hasta count que se hayan convertido los 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 LC_TYPE categoría de la configuración regional actual.

La 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 usar mbsrlen en lugar de mbslen, si se usa una llamada posterior a mbsrtowcs en lugar de mbstowcs.

Si wcstr no es un puntero nulo, al objeto de puntero al que apunta mbstr se le asigna un puntero NULO si se detiene la conversión porque se alcanzó un carácter nulo de terminación. De lo contrario, se le asigna la dirección justo después del último carácter multibyte convertido, si existe. Permite que una llamada de función posterior reinicie la conversión donde se detuvo esta llamada.

Si el wcstr argumento es un puntero nulo, se omite el count argumento y mbsrtowcs devuelve el tamaño necesario 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 mbstr de caracteres no tiene una representación de caracteres multibyte correspondiente, se devuelve -1 y errno se establece en EILSEQ.

Si mbstr es un puntero nulo, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. 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, 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 mbsrtowcs función es segura para varios subprocesos siempre y cuando no haya ninguna función en el subproceso actual, setlocale siempre y cuando esta función se esté ejecutando y el mbstate argumento no sea un puntero nulo.

Requisitos

Routine	Encabezado necesario
mbsrtowcs	<wchar.h>

Consulte también

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