Namespaces
Variants

    wcrtomb, wcrtomb_s

    De es.cppreference.net
     
    C
     
    Biblioteca de cadenas
     
    Cadenas multibyte terminadas en nulo
     
    Definido en el encabezado <wchar.h> 
    size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);
    		(1) (desde C95)
    (hasta C99)    		 
    size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);
    		(desde C99) 
    errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);
    		(2) (desde C11)

    Convierte un carácter ancho a su representación multibyte estrecha.

    1) Si s no es un puntero nulo, la función determina el número de bytes necesarios para almacenar la representación multibyte del carácter wc (incluyendo cualquier secuencia de desplazamiento, y teniendo en cuenta el estado actual de conversión multibyte *ps), y almacena la representación multibyte en el arreglo de caracteres cuyo primer elemento es apuntado por s, actualizando *ps según sea necesario. Como máximo MB_CUR_MAX bytes pueden ser escritos por esta función.
    Si s es un puntero nulo, la llamada es equivalente a wcrtomb(buf, L'\0', ps) para algún búfer interno buf.
    Si wc es el carácter ancho nulo L'\0', se almacena un byte nulo, precedido por cualquier secuencia de desplazamiento necesaria para restaurar el estado de desplazamiento inicial y el parámetro de estado de conversión *ps se actualiza para representar el estado de desplazamiento inicial.
    Si la macro de entorno __STDC_ISO_10646__ está definida, los valores del tipo wchar_t son los mismos que los identificadores cortos de los caracteres en el conjunto requerido de Unicode (típicamente codificación UTF-32); de lo contrario, está definido por la implementación. En cualquier caso, la codificación de caracteres multibyte utilizada por esta función está especificada por la configuración regional C actualmente activa.
    2) Igual que (1), excepto que
    si s es un puntero nulo, la llamada es equivalente a wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) con variables internas retval y buf (cuyo tamaño es mayor que MB_CUR_MAX)
    el resultado se devuelve en el parámetro de salida retval
    los siguientes errores se detectan en tiempo de ejecución y llaman a la función manejador de restricciones actualmente instalada:
    • retval o ps es un puntero nulo.
    • ssz es cero o mayor que RSIZE_MAX (a menos que s sea nulo)
    • ssz es menor que el número de bytes que se escribirían (a menos que s sea nulo)
    • s es un puntero nulo pero ssz no es cero
    Como con todas las funciones con verificación de límites, wcrtomb_s solo está garantizado estar 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 <wchar.h>.

    Parámetros

    s - puntero al arreglo de caracteres estrechos donde se almacenará el carácter multibyte
    wc - el carácter ancho a convertir
    ps - puntero al objeto de estado de conversión utilizado al interpretar la cadena multibyte
    ssz - número máximo de bytes a escribir (el tamaño del búfer s)
    retval - puntero a un parámetro de salida donde se almacenará el resultado (número de bytes en la cadena multibyte incluyendo cualquier secuencia de desplazamiento)

    Valor de retorno

    1) En caso de éxito, devuelve el número de bytes (incluyendo cualquier secuencia de desplazamiento) escritos en el arreglo de caracteres cuyo primer elemento es apuntado por s.
    En caso de fallo (si wc no es un carácter ancho válido), devuelve (size_t)-1, almacena EILSEQ en errno, y deja *ps en un estado no especificado.
    2) Devuelve cero en caso de éxito y distinto de cero en caso de fallo, en cuyo caso, s[0] se establece a '\0' (a menos que s sea nulo o ssz sea cero o mayor que RSIZE_MAX) y *retval se establece a (size_t)-1 (a menos que retval sea nulo)

    Ejemplo

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

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -1)
            break;
        p += rc;
    }
 
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [ ", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%#x ", +(unsigned char)out[x]);
    puts("]");
}

    Salida: 

    Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

    Referencias

    • Estándar C23 (ISO/IEC 9899:2024):
    • 7.29.6.3.3 La función wcrtomb (p: TBD)
    • K.3.9.3.1.1 La función wcrtomb_s (p: TBD)
    • Estándar C17 (ISO/IEC 9899:2018):
    • 7.29.6.3.3 La función wcrtomb (p: TBD)
    • K.3.9.3.1.1 La función wcrtomb_s (p: TBD)
    • Estándar C11 (ISO/IEC 9899:2011):
    • 7.29.6.3.3 La función wcrtomb (p: 444)
    • K.3.9.3.1.1 La función wcrtomb_s (p: 647-648)
    • Estándar C99 (ISO/IEC 9899:1999):
    • 7.24.6.3.3 La función wcrtomb (p: 390)

    Véase también

    (C11)
    		 convierte un carácter ancho a su representación multibyte
    (función)
    (C95)
    		 convierte el siguiente carácter multibyte a carácter ancho, dado el estado
    (función)
    Documentación de C++ para wcrtomb