Namespaces
Variants

mbstowcs, mbstowcs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Défini dans l'en-tête <stdlib.h>
(1)
size_t mbstowcs ( wchar_t * dst, const char * src, size_t len )
(jusqu'à C99)
size_t mbstowcs ( wchar_t * restrict dst, const char * restrict src, size_t len )
(depuis C99)
errno_t mbstowcs_s ( size_t * restrict retval, wchar_t * restrict dst,
rsize_t dstsz, const char * restrict src, rsize_t len ) ;
(2) (depuis C11)
1) Convertit une chaîne de caractères multioctets du tableau dont le premier élément est pointé par src en sa représentation en caractères larges. Les caractères convertis sont stockés dans les éléments successifs du tableau pointé par dst . Pas plus de len caractères larges sont écrits dans le tableau de destination.
Chaque caractère est converti comme par un appel à mbtowc , sauf que l'état de conversion mbtowc n'est pas affecté. La conversion s'arrête si :
* Le caractère nul multioctet a été converti et stocké.
* Un caractère multioctet non valide (dans les paramètres régionaux C actuels) a été rencontré.
* Le prochain caractère large à stocker dépasserait len .
Si src et dst se chevauchent, le comportement est indéfini
2) Identique à (1) , sauf que
* la conversion est effectuée comme par mbrtowc , et non par mbtowc
* la fonction retourne son résultat en tant que paramètre de sortie retval
* si aucun caractère nul n'a été écrit dans dst après que len caractères larges aient été écrits, alors L ' \0 ' est stocké dans dst[len] , ce qui signifie que len+1 caractères larges au total sont écrits
* si dst est un pointeur nul, le nombre de caractères larges qui seraient produits est stocké dans * retval
* la fonction écrase le tableau de destination à partir du caractère nul de fin et jusqu'à dstsz
* Si src et dst se chevauchent, le comportement n'est pas spécifié.
* les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contraintes actuellement installée :
  • retval ou src est un pointeur nul
  • dstsz ou len est supérieur à RSIZE_MAX/sizeof(wchar_t) (sauf si dst est nul)
  • dstsz n'est pas zéro (sauf si dst est nul)
  • Il n'y a pas de caractère nul dans les premiers dstsz caractères multi-octets du tableau src et len est supérieur à dstsz (sauf si dst est nul)
Comme pour toutes les fonctions à vérification de limites, mbstowcs_s n'est garantie d'être disponible que si __STDC_LIB_EXT1__ est défini par l'implémentation et si l'utilisateur définit __STDC_WANT_LIB_EXT1__ à la constante entière 1 avant d'inclure <stdlib.h> .

Table des matières

Notes

Dans la plupart des implémentations, mbstowcs met à jour un objet statique global de type mbstate_t pendant son traitement de la chaîne, et ne peut pas être appelée simultanément par deux threads, mbsrtowcs devrait être utilisée dans de tels cas.

POSIX spécifie une extension courante : si dst est un pointeur nul, cette fonction retourne le nombre de caractères larges qui seraient écrits dans dst , s'ils étaient convertis. Un comportement similaire est standard pour mbstowcs_s et pour mbsrtowcs .

Paramètres

dst - pointeur vers le tableau de caractères larges où la chaîne large sera stockée
src - pointeur vers le premier élément d'une chaîne multioctet terminée par un caractère nul à convertir
len - nombre de caractères larges disponibles dans le tableau pointé par dst
dstsz - nombre maximum de caractères larges qui seront écrits (taille du tableau dst )
retval - pointeur vers un objet size_t où le résultat sera stocké

Valeur de retour

1) En cas de succès, retourne le nombre de caractères larges, à l'exclusion du L ' \0 ' terminal, écrits dans le tableau de destination. En cas d'erreur de conversion (si un caractère multioctet invalide a été rencontré), retourne ( size_t ) - 1 .
2) zéro en cas de succès (auquel cas le nombre de caractères larges, à l'exclusion du zéro terminal, qui ont été ou auraient été écrits dans dst , est stocké dans * retval ), non-zéro en cas d'erreur. En cas de violation de contrainte d'exécution, stocke ( size_t ) - 1 dans * retval (sauf si retval est nul) et définit dst [ 0 ] à L ' \0 ' (sauf si dst est nul ou dstmax est zéro ou supérieur à RSIZE_MAX )

Exemple

Exécuter ce code 
#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);
}

Sortie : 

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

Références

  • Norme C11 (ISO/CEI 9899:2011) :
  • 7.22.8.1 La fonction mbstowcs (p. 359)
  • K.3.6.5.1 La fonction mbstowcs_s (p. 611-612)
  • Norme C99 (ISO/CEI 9899:1999) :
  • 7.20.8.1 La fonction mbstowcs (p. 323)
  • Norme C89/C90 (ISO/CEI 9899:1990) :
  • 4.10.8.1 La fonction mbstowcs

Voir aussi

(C95) (C11)
convertit une chaîne de caractères multioctets étroite en chaîne large, avec état
(fonction)
(C11)
convertit une chaîne large en chaîne de caractères multioctets étroite
(fonction)
Documentation C++ pour mbstowcs