NOMBRE
mbstowcs − convierte una cadena multibyte en una cadena de caracteres anchos
SINOPSIS
#include <stdlib.h>
size_t mbstowcs (wchar_t *dest, const char *src, size_t n);
DESCRIPCIÓN
Si dest no es un puntero NULL, la función mbstowcs convierte la cadena multibyte src a una cadena de caracteres anchos que comienza en dest. Como mucho, se escriben n caracteres anchos en dest. La conversión comienza en el estado inicial. La conversión se puede detener por tres razones:
1. Se ha encontrado una secuencia multibyte inválida. Es este caso, la función devuelve (size_t)(-1).
2. Se han almacenado n caracteres anchos distintos de L’\0’ en dest. En este caso, se devuelve el número de caracteres anchos escritos en dest, aunque el estado de cambios, en este punto, se pierde.
3. Se ha convertido toda la cadena multibyte, incluyendo el ’\0’ que la termina. En esta caso, se devuelve el número de caracteres anchos escritos en dest, excluyendo el carácter L’\0’ terminador.
El programador debe asegurar que hay espacio en dest para, al menos, n caracters anchos.
Si dest es NULL, n se ignora, y la conversión procede como antes, salvo que los caracteres anchos obtenidos no se escriben en memoria y que no hay límite de longitud.
Para evitar el caso 2 anterior, el programador debería asegurarse de que n es mayor o igual que mbstowcs(NULL,src,0)+1.
VALOR DEVUELTO
La función mbstowcs devuelve el número de caracteres anchos que componen la parte convertida de la cadena de caracteres anchos, sin incluir el carácter ancho nulo terminador. Si se encuentra una secuencia multibyte inválida, devuelve (size_t)(-1).
CONFORME A
ISO/ANSI C, UNIX98
VÉASE TAMBIÉN
OBSERVACIONES
El comportamiento de mbstowcs depende de la categoría LC_CTYPE de la localización actual.
La función mbsrtowcs proporciona una interfaz mejor con la misma funcionalidad.