Namespaces
Variants

    mbstowcs, mbstowcs_s

    De es.cppreference.net
     
    C
     
    Biblioteca de cadenas
     
    Cadenas multibyte terminadas en nulo
     
    Definido en el encabezado <stdlib.h> 
    size_t mbstowcs( wchar_t* dst, const char* src, size_t len)
    		(1) (hasta C99) 
    size_t mbstowcs( wchar_t* restrict dst, const char* restrict src, size_t len)
    		(desde C99) 
    errno_t mbstowcs_s(size_t* restrict retval, wchar_t* restrict dst,
                  rsize_t dstsz, const char* restrict src, rsize_t len);
    		(2) (desde C11)
    1) Convierte una cadena de caracteres multibyte desde el arreglo cuyo primer elemento es apuntado por src a su representación de caracteres anchos. Los caracteres convertidos se almacenan en los elementos sucesivos del arreglo apuntado por dst. No se escriben más de len caracteres anchos en el arreglo de destino.
    Cada carácter se convierte como si se llamara a mbtowc, excepto que el estado de conversión de mbtowc no se ve afectado. La conversión se detiene si:
    • El carácter nulo multibyte fue convertido y almacenado.
    • Se encontró un carácter multibyte no válido (en la configuración regional C actual).
    • El siguiente carácter ancho a almacenar excedería len.
    Si src y dst se superponen, el comportamiento no está definido
    2) Igual que (1), excepto que
    • la conversión se realiza como si fuera mediante mbrtowc, no mediante mbtowc
    • la función devuelve su resultado como un parámetro de salida retval
    • si no se escribió un carácter nulo en dst después de escribir len caracteres anchos, entonces L'\0' se almacena en dst[len], lo que significa que se escriben len+1 caracteres anchos en total
    • si dst es un puntero nulo, el número de caracteres anchos que se producirían se almacena en *retval
    • la función sobrescribe el arreglo de destino desde el nulo terminador hasta dstsz
    • Si src y dst se superponen, el comportamiento no está especificado.
    • Se detectan los siguientes errores en tiempo de ejecución y se llama a la función constraint handler actualmente instalada:
    • retval o src es un puntero nulo
    • dstsz o len es mayor que RSIZE_MAX / sizeof(wchar_t) (a menos que dst sea nulo)
    • dstsz no es cero (a menos que dst sea nulo)
    • No hay ningún carácter nulo en los primeros dstsz caracteres multibyte en el arreglo src y len es mayor que dstsz (a menos que dst sea nulo)
    Como todas las funciones con verificación de límites, mbstowcs_s solo está garantizado que esté disponible si __STDC_LIB_EXT1__ está definido por la implementación y si el usuario define __STDC_WANT_LIB_EXT1__ como la constante entera 1 antes de incluir <stdlib.h>.

    Notas

    En la mayoría de las implementaciones, mbstowcs actualiza un objeto estático global de tipo mbstate_t mientras procesa la cadena, y no puede ser llamado simultáneamente por dos hilos; mbsrtowcs debería usarse en tales casos.

    POSIX especifica una extensión común: si dst es un puntero nulo, esta función devuelve el número de caracteres anchos que se escribirían en dst, si se convirtieran. Un comportamiento similar es estándar para mbstowcs_s y para mbsrtowcs.

    Parámetros

    dst - puntero al arreglo de caracteres anchos donde se almacenará la cadena ancha
    src - puntero al primer elemento de una cadena multibyte terminada en nulo a convertir
    len - número de caracteres anchos disponibles en el arreglo apuntado por dst
    dstsz - número máximo de caracteres anchos que se escribirán (tamaño del arreglo dst)
    retval - puntero a un objeto size_t donde se almacenará el resultado

    Valor de retorno

    1) En caso de éxito, devuelve el número de caracteres anchos, excluyendo el L'\0' terminador, escritos en el arreglo de destino. En caso de error de conversión (si se encontró un carácter multibyte no válido), devuelve (size_t)-1.
    2) cero en caso de éxito (en cuyo caso el número de caracteres anchos excluyendo el cero terminador que fueron, o se escribirían en dst, se almacena en *retval), distinto de cero en caso de error. En caso de violación de restricción en tiempo de ejecución, almacena (size_t)-1 en *retval (a menos que retval sea nulo) y establece dst[0] en L'\0' (a menos que dst sea nulo o dstmax sea cero o mayor que RSIZE_MAX)

    Ejemplo

    Ejecutar este código
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

    Salida: 

    MB string: zß水🍌
Wide string: zß水🍌

    Referencias

    • Estándar C23 (ISO/IEC 9899:2024):
    • 7.22.8.1 La función mbstowcs (p: TBD)
    • K.3.6.5.1 La función mbstowcs_s (p: TBD)
    • Estándar C17 (ISO/IEC 9899:2018):
    • 7.22.8.1 La función mbstowcs (p: TBD)
    • K.3.6.5.1 La función mbstowcs_s (p: TBD)
    • Estándar C11 (ISO/IEC 9899:2011):
    • 7.22.8.1 La función mbstowcs (p: 359)
    • K.3.6.5.1 La función mbstowcs_s (p: 611-612)
    • Estándar C99 (ISO/IEC 9899:1999):
    • 7.20.8.1 La función mbstowcs (p: 323)
    • Estándar C89/C90 (ISO/IEC 9899:1990):
    • 4.10.8.1 La función mbstowcs

    Véase también

    (C95)(C11)
    		 convierte una cadena de caracteres multibyte estrecha a cadena ancha, dado estado
    (función)
    (C11)
    		 convierte una cadena ancha a cadena de caracteres multibyte estrecha
    (función)
    Documentación de C++ para mbstowcs