Namespaces
Variants

wcrtomb, wcrtomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definido en el encabezado <wchar.h>
(1)
size_t wcrtomb ( char * s, wchar_t wc, mbstate_t * ps ) ;
(desde C95)
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 del carácter multibyte de wc (incluyendo cualquier secuencia de cambio, y tomando en cuenta el estado actual de conversión multibyte * ps ), y almacena la representación del carácter multibyte en el arreglo de caracteres cuyo primer elemento está 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 cambio necesaria para restaurar el estado de cambio inicial y el parámetro de estado de conversión * ps se actualiza para representar el estado de cambio inicial.
Si la macro del entorno __STDC_ISO_10646__ está definida, los valores del tipo wchar_t son iguales a los identificadores cortos de los caracteres en el conjunto requerido de Unicode (normalmente 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 de 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 constraint handler 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 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 <wchar.h> .

Contenidos

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 cambio)

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 está apuntado por s .
En caso de fallo (si wc no es un carácter ancho válido), retorna ( size_t ) - 1 , almacena EILSEQ en errno , y deja * ps en un estado no especificado.
2) Retorna 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 <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.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 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