Namespaces
Variants

    wcstombs, wcstombs_s

    De es.cppreference.net
     
    C
     
    Biblioteca de cadenas
     
    Cadenas multibyte terminadas en nulo
     
    Definido en el encabezado <stdlib.h> 
    size_t wcstombs( char* dst, const wchar_t* src, size_t len );
    		(1) (hasta C99) 
    size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );
    		(desde C99) 
    errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
                    const wchar_t* restrict src, rsize_t len );
    		(2) (desde C11)
    1) Convierte una secuencia de caracteres anchos desde el arreglo cuyo primer elemento es apuntado por src a su representación multibyte estrecha que comienza en el estado de desplazamiento inicial. Los caracteres convertidos se almacenan en los elementos sucesivos del arreglo de caracteres apuntado por dst. No se escriben más de len bytes en el arreglo destino.
    Cada carácter se convierte como si se llamara a wctomb, excepto que el estado de conversión de wctomb no se ve afectado. La conversión se detiene si:
    • El carácter nulo L'\0' fue convertido y almacenado. Los bytes almacenados en este caso son la secuencia de desactivación (si es necesario) seguida de '\0',
    • Se encontró un wchar_t que no corresponde a un carácter válido en la configuración regional C actual.
    • El siguiente carácter multibyte a almacenar excedería len.
    Si src y dst se superponen, el comportamiento no está especificado.
    2) Igual que (1), excepto que
    • la conversión es como si se llamara a wcrtomb, no a wctomb
    • la función devuelve su resultado como un parámetro de salida retval
    • si la conversión se detiene sin escribir un carácter nulo, la función almacenará '\0' en el siguiente byte en dst, que puede ser dst[len] o dst[dstsz], lo que ocurra primero (lo que significa que se pueden escribir hasta len+1/dstsz+1 bytes en total). En este caso, puede que no se escriba ninguna secuencia de desactivación antes del terminador nulo.
    • si dst es un puntero nulo, el número de bytes que se producirían se almacena en *retval
    • la función sobrescribe el arreglo destino desde el terminador nulo y hasta dstsz
    • Si src y dst se superponen, el comportamiento no está especificado.
    • los siguientes errores se detectan en tiempo de ejecución y llaman a la función manejador de restricciones actualmente instalada:
    • retval o src es un puntero nulo
    • dstsz o len es mayor que RSIZE_MAX (a menos que dst sea nulo)
    • dstsz no es cero (a menos que dst sea nulo)
    • len es mayor que dstsz y la conversión no encuentra nulo o error de codificación en el arreglo src en el momento en que se alcanza dstsz (a menos que dst sea nulo)
    Como con todas las funciones con verificación de límites, wcstombs_s solo se garantiza 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, wcstombs actualiza un objeto estático global de tipo mbstate_t a medida que procesa la cadena, y no puede ser llamado simultáneamente por dos hilos; en tales casos, se debe usar wcsrtombs o wcstombs_s.

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

    Parámetros

    dst - puntero al arreglo de caracteres estrechos donde se almacenará el carácter multibyte
    src - puntero al primer elemento de una cadena ancha terminada en nulo a convertir
    len - número de bytes disponibles en el arreglo apuntado por dst
    dstsz - número máximo de bytes 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 bytes (incluyendo cualquier secuencia de desplazamiento, pero excluyendo el '\0' terminador) escritos en el arreglo de caracteres cuyo primer elemento es apuntado por dst. En caso de error de conversión (si se encontró un carácter ancho inválido), devuelve (size_t)-1.
    2) Devuelve cero en caso de éxito (en cuyo caso el número de bytes excluyendo el cero terminador que fueron, o serían escritos en dst, se almacena en *retval), distinto de cero en caso de error. En caso de una 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 '\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>

int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];

    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx = 0; ndx < sizeof src / sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx = 0; ndx < sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

    Salida: 

    wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

    Referencias

    • Estándar C23 (ISO/IEC 9899:2024):
    • 7.22.8.2 La función wcstombs (p: TBD)
    • K.3.6.5.2 La función wcstombs_s (p: TBD)
    • Estándar C17 (ISO/IEC 9899:2018):
    • 7.22.8.2 La función wcstombs (p: TBD)
    • K.3.6.5.2 La función wcstombs_s (p: TBD)
    • Estándar C11 (ISO/IEC 9899:2011):
    • 7.22.8.2 La función wcstombs (p: 360)
    • K.3.6.5.2 La función wcstombs_s (p: 612-614)
    • Estándar C99 (ISO/IEC 9899:1999):
    • 7.20.8.2 La función wcstombs (p: 324)
    • Estándar C89/C90 (ISO/IEC 9899:1990):
    • 4.10.8.2 La función wcstombs

    Véase también

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