`wcsrtombs`

Article
10/12/2023

Convertit une chaîne de caractères larges dans sa représentation de chaîne de caractères multioctets. Une version plus sécurisée de cette fonction est disponible ; voir wcsrtombs_s.

Syntaxe

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

Paramètres

mbstr
Emplacement adresse de la chaîne de caractères multioctets convertie obtenue.

wcstr
Pointe indirectement vers l’emplacement de la chaîne de caractères larges à convertir.

count
Nombre de caractères à convertir.

mbstate
Un pointeur vers un objet d'état de conversion mbstate_t.

Valeur retournée

Retourne le nombre d’octets correctement convertis, sans l’octet Null de fin (le cas échéant) ou -1 si une erreur s’est produite.

Notes

La fonction wcsrtombs convertit une chaîne de caractères larges, en commençant dans l’état de conversion spécifié dans mbstate, à partir des valeurs pointées indirectement dans wcstr, en adresse de mbstr. La conversion se poursuit pour chaque caractère jusqu’à ce qu’un caractère large de fin Null ou un caractère non correspondant soit rencontré ou dès que le caractère suivant dépasse la limite contenue dans count. Si la fonction wcsrtombs rencontre le caractère Null de caractère large (L'\0') avant ou quand count est atteint, elle le convertit en 0 de 8 bits et s’arrête.

Par conséquent, la chaîne de caractères multioctets au niveau de mbstr se termine par un caractère Null seulement si wcsrtombs rencontre un caractère Null de caractère large pendant la conversion. Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement de wcsrtombs n'est pas défini. wcsrtombs est affecté par la catégorie LC_TYPE des paramètres régionaux actuels.

La wcsrtombs fonction diffère de , _wcstombs_l par wcstombssa capacité de redémarrage. L'état de la conversion est stocké dans mbstate pour les appels suivants à la même ou à d'autres fonctions redémarrables. Les résultats ne sont pas définis quand l'utilisation de fonctions redémarrables est combinée avec l'utilisation de fonctions non redémarrables. Par exemple, une application utiliserait wcsrlen plutôt que wcsnlen si un appel ultérieur à wcsrtombs était utilisé à la place de wcstombs.

Si l’argument mbstr a la valeur NULL, wcsrtombs retourne la taille requise de la chaîne de destination en octets. Si mbstate a la valeur null, l’état de conversion mbstate_t interne est utilisé. Si la séquence wchar de caractères n’a pas de représentation de caractère multioctet correspondante, un -1 est retourné et la valeur errno est définie EILSEQsur .

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

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Exceptions

La wcsrtombs fonction est sécurisée multithread tant qu’aucune fonction dans les appels setlocale de thread actuel pendant l’exécution de cette fonction et n’est mbstate pas null.

Exemple

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

Spécifications

Routine	En-tête requis
`wcsrtombs`	<wchar.h>

Voir aussi

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Share via