Namespaces
Variants

wctomb, wctomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definido en el encabezado <stdlib.h>
int wctomb ( char * s, wchar_t wc ) ;
(1)
errno_t wctomb_s ( int * restrict status, char * restrict s, rsize_t ssz, wchar_t wc ) ;
(2) (desde C11)
1) Convierte un carácter ancho wc a codificación multibyte y lo almacena (incluyendo cualquier secuencia de desplazamiento) en el array de caracteres cuyo primer elemento está apuntado por s . No se almacenan más de MB_CUR_MAX caracteres. La conversión está afectada por la categoría LC_CTYPE de la configuración regional actual.
Si wc es el carácter nulo, el byte nulo se escribe en s , precedido por cualquier secuencia de cambio necesaria para restaurar el estado de cambio inicial.
Si s es un puntero nulo, esta función restablece el estado de conversión global y determina si se utilizan secuencias de desplazamiento.
2) Igual que (1) , excepto que el resultado se devuelve en el parámetro de salida status y los siguientes errores se detectan en tiempo de ejecución y llaman a la función constraint handler actualmente instalada:
  • ssz es menor que el número de bytes que se escribirían (a menos que s sea null)
  • ssz es mayor que RSIZE_MAX (a menos que s sea null)
  • s es un puntero nulo pero ssz no es cero
Como con todas las funciones con verificación de límites, wctomb_s solo está garantizada 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> .

Contenidos

Notas

Cada llamada a wctomb actualiza el estado de conversión global interno (un objeto estático de tipo mbstate_t , conocido únicamente por esta función). Si la codificación multibyte utiliza estados de cambio, esta función no es reentrante. En cualquier caso, múltiples hilos no deberían llamar a wctomb sin sincronización: wcrtomb o wctomb_s pueden usarse en su lugar.

A diferencia de la mayoría de las funciones con verificación de límites, wctomb_s no termina su salida con nulo, porque está diseñada para usarse en bucles que procesan cadenas carácter por carácter.

Parámetros

s - puntero al arreglo de caracteres para salida
wc - carácter ancho a convertir
ssz - número máximo de bytes a escribir en s (tamaño del arreglo s )
status - puntero a un parámetro de salida donde se almacenará el resultado (longitud de la secuencia multibyte o el estado de la secuencia de desplazamiento)

Valor de retorno

1) Si s no es un puntero nulo, devuelve el número de bytes contenidos en la representación multibyte de wc o - 1 si wc no es un carácter válido.
Si s es un puntero nulo, restablece su estado de conversión interno para representar el estado de desplazamiento inicial y retorna ​ 0 ​ si la codificación multibyte actual no depende del estado (no utiliza secuencias de desplazamiento) o un valor distinto de cero si la codificación multibyte actual depende del estado (utiliza secuencias de desplazamiento).
2) cero en caso de éxito, en cuyo caso la representación multibyte de wc se almacena en s y su longitud se almacena en * status , o, si s es nulo, el estado de la secuencia de desplazamiento se almacena en status ). Diferente de cero en error de codificación o violación de restricción en tiempo de ejecución, en cuyo caso ( size_t ) - 1 se almacena en * status . El valor almacenado en * status nunca excede MB_CUR_MAX

Ejemplo

Ejecutar este código 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
    char mb[MB_CUR_MAX];
    int len = wctomb(mb, wc);
    printf("wide char '%lc' -> multibyte char [", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
    printf("]\n");
}
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

Salida posible: 

MB_CUR_MAX = 6
State-dependent encoding? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

Referencias

  • Estándar C17 (ISO/IEC 9899:2018):
  • 7.22.7.3 La función wctomb (p: 261)
  • K.3.6.4.1 La función wctomb_s (p: 443)
  • Estándar C11 (ISO/IEC 9899:2011):
  • 7.22.7.3 La función wctomb (p: 358-359)
  • K.3.6.4.1 La función wctomb_s (p: 610-611)
  • Estándar C99 (ISO/IEC 9899:1999):
  • 7.20.7.3 La función wctomb (p: 322-323)
  • Estándar C89/C90 (ISO/IEC 9899:1990):
  • 4.10.7.3 La función wctomb

Véase también

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