Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definido en el encabezado <stdlib.h>
(1)
size_t wcstombs ( char * dst, const wchar_t * src, size_t len ) ;
(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 del array cuyo primer elemento está 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 array char apuntado por dst . No se escriben más de len bytes en el array de destino.
Cada carácter se convierte como si mediante una llamada 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 desbloqueo (si es necesaria) seguida por ' \0 ' ,
* Se encontró un wchar_t que no corresponde a un carácter válido en la configuración regional actual de C.
* 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 fuera mediante wcrtomb , no mediante 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] , el 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 una secuencia de desbloqueo antes del nulo terminador.
* si dst es un puntero nulo, el número de bytes que se producirían se almacena en * retval
* la función sobrescribe el array de destino desde el carácter nulo de terminación 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 constraint handler 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 un nulo o error de codificación en el arreglo src para cuando se alcanza dstsz (a menos que dst sea nulo)
Como con todas las funciones de verificación de límites, wcstombs_s solo está garantizada de 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 <stdlib.h> .

Contenidos

Notas

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

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

Parámetros

dst - puntero al array 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 array apuntado por dst
dstsz - número máximo de bytes que serán escritos (tamaño del dst array)
retval - puntero a un objeto size_t donde se almacenará el resultado

Valor de retorno

1) En caso de éxito, retorna el número de bytes (incluyendo cualquier secuencia de desplazamiento, pero excluyendo el terminador ' \0 ' ) escritos en el arreglo de caracteres cuyo primer elemento está apuntado por dst . En error de conversión (si se encontró un carácter ancho inválido), retorna ( size_t ) - 1 .
2) Retorna 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 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 ] a ' \0 ' (a menos que dst sea nulo o dstmax sea cero o mayor que RSIZE_MAX )

Ejemplo

Ejecutar este código 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
int main(void)
{
    // 4 caracteres anchos
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // ocupan 10 bytes en 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 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