Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Definido en el encabezado <stdlib.h>
(1)
size_t mbstowcs ( wchar_t * dst, const char * src, size_t len )
(hasta C99)
size_t mbstowcs ( wchar_t * restrict dst, const char * restrict src, size_t len )
(desde C99)
errno_t mbstowcs_s ( size_t * restrict retval, wchar_t * restrict dst,
rsize_t dstsz, const char * restrict src, rsize_t len ) ;
(2) (desde C11)
1) Convierte una cadena de caracteres multibyte desde el array cuyo primer elemento está apuntado por src a su representación de caracteres anchos. Los caracteres convertidos se almacenan en los elementos sucesivos del array apuntado por dst . No se escriben más de len caracteres anchos en el array de destino.
Cada carácter se convierte como si mediante una llamada a mbtowc , excepto que el estado de conversión de mbtowc no se ve afectado. La conversión se detiene si:
* El carácter nulo multibyte fue convertido y almacenado.
* Se encontró un carácter multibyte no válido (en la configuración regional actual de C).
* El siguiente carácter ancho a almacenar excedería len .
Si src y dst se superponen, el comportamiento es indefinido
2) Igual que (1) , excepto que
* la conversión es como si fuera mediante mbrtowc , no mediante mbtowc
* la función devuelve su resultado como un parámetro de salida retval
* si ningún carácter nulo fue escrito en dst después de que len caracteres anchos fueron escritos, entonces L ' \0 ' se almacena en dst[len] , lo que significa que se escriben len+1 caracteres anchos en total
* si dst es un puntero nulo, el número de caracteres anchos 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 manejador de restricciones actualmente instalada:
  • retval o src es un puntero nulo
  • dstsz o len es mayor que RSIZE_MAX/sizeof(wchar_t) (a menos que dst sea nulo)
  • dstsz no es cero (a menos que dst sea nulo)
  • No hay carácter nulo en los primeros dstsz caracteres multibyte en el arreglo src y len es mayor que dstsz (a menos que dst sea nulo)
Como con todas las funciones con verificación de límites, mbstowcs_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

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

POSIX especifica una extensión común: si dst es un puntero nulo, esta función retorna el número de caracteres anchos que serían escritos en dst , si se convirtieran. Un comportamiento similar es estándar para mbstowcs_s y para mbsrtowcs .

Parámetros

dst - puntero al arreglo de caracteres anchos donde se almacenará la cadena ancha
src - puntero al primer elemento de una cadena multibyte terminada en nulo a convertir
len - número de caracteres anchos disponibles en el arreglo apuntado por dst
dstsz - número máximo de caracteres anchos 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, devuelve el número de caracteres anchos, excluyendo el terminador L ' \0 ' , escritos en el array de destino. En caso de error de conversión (si se encontró un carácter multibyte inválido), devuelve ( size_t ) - 1 .
2) cero en caso de éxito (en cuyo caso el número de caracteres anchos 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 L ' \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 <locale.h>
#include <stdlib.h>
#include <wchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}

Salida: 

MB string: zß水🍌
Wide string: zß水🍌

Referencias

  • Estándar C11 (ISO/IEC 9899:2011):
  • 7.22.8.1 La función mbstowcs (p: 359)
  • K.3.6.5.1 La función mbstowcs_s (p: 611-612)
  • Estándar C99 (ISO/IEC 9899:1999):
  • 7.20.8.1 La función mbstowcs (p: 323)
  • Estándar C89/C90 (ISO/IEC 9899:1990):
  • 4.10.8.1 La función mbstowcs

Véase también

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