mbsrtowcs

Article
03/04/2013

Convertit une chaîne à caractères multioctets à une chaîne correspondante à caractères larges.un plus version sécurisée de cette fonction est disponible ; consultez mbsrtowcs.

size_t mbsrtowcs(
   wchar_t *wcstr,
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t mbsrtowcs(
   wchar_t (&wcstr)[size],
   const char **mbstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Paramètres

[out] wcstr
L'emplacement de l'adresse de la chaîne à caractères larges convertie résultante.
[in] mbstr
Indirectement pointe vers l'emplacement de la chaîne à caractères multioctets à convertir.
[in] count
Le nombre de caractères à convertir.
[in] mbstate
Un pointeur vers un objet du rapport de conversion d' mbstate_t .

Valeur de retour

Retourne le numéro de mots avec succès convertis, sans null de fin le mot null (le cas échéant), sinon l'si une erreur s'est produite.

Notes

La fonction d' mbsrtowcs convertit une chaîne de caractères multioctets, en commençant dans le rapport de conversion spécifié contenu dans mbstate, de l'aigu indirect de valeurs à dans mbstr, dans l'adresse d' wcstr.La conversion continuera pour chaque caractère until : après que la valeur null de fin le caractère multioctets soit produit, lorsqu'un caractère non-concordant est produit ou lorsque le caractère suivant dépasse la limite contenue dans count.Si mbsrtowcs rencontre le caractère NULL multioctets (" \ 0 ") ou avant ou lorsque count se produit, il convertit en null 16 bits terminant le caractère et s'arrête.

Ainsi, la chaîne à caractères larges à l'adresse wcstr se terminant par null uniquement si mbsrtowcs rencontre un caractère Null multioctets pendant la conversion.Si les séquences pointées par mbstr et wcstr se chevauchent, le comportement d' mbsrtowcs n'est pas défini.mbsrtowcs est affectée par la catégorie de LC_TYPE des paramètres régionaux.

la fonction d' mbsrtowcs diffère de mbstowcs, _mbstowcs_l par sa capacité à redémarrer.Le rapport de conversion est stocké dans mbstate pour les appels suivants à la même transparence ou à d'autres fonctions restartable.Les résultats sont indéfinis en combinant l'utilisation des fonctions restartable et nonrestartable.Par exemple, une application utilise mbsrlen plutôt qu' mbslen, si un appel suivant à mbsrtowcs où utilisé au lieu d' mbstowcs.

Si l'argument d' wcstr est NULL, mbsrtombs retourne la taille requise dans les mots de la chaîne de destination.Si mbstate est null, le rapport de conversion interne d' mbstate_t est utilisé.Si la séquence de caractères wchar n'a pas de représentation correspondante de caractères multioctets, une valeur est retournée par et errno est défini à EILSEQ.

si mbstr est NULL, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution de se poursuivre, des ensembles errno de cette fonction à EINVAL et retourne -1.

En C++, cette fonction a une surcharge de modèle qui appelle les homologues plus récentes et sécurisées de cette fonction.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Exceptions

La fonction d' mbsrtowcs est multithread-safe tant qu'aucune fonction dans le thread actuel n'appelle setlocale bien que cette fonction s'exécute et mbstate n'est pas null.