mbstowcs, _mbstowcs_l

 

Pour obtenir la dernière documentation sur Visual Studio 2017, consultez Documentation Visual Studio 2017.

Convertit une séquence de caractères multioctets en une séquence de caractères larges correspondante. Des versions plus sécurisées de ces fonctions sont disponibles. consultez la page mbstowcs_s, _mbstowcs_s_l.

size_t mbstowcs(  
   wchar_t *wcstr,  
   const char *mbstr,  
   size_t count   
);  
size_t _mbstowcs_l(  
   wchar_t *wcstr,  
   const char *mbstr,  
   size_t count,  
   _locale_t locale  
);  
template <size_t size>  
size_t mbstowcs(  
   wchar_t (&wcstr)[size],  
   const char *mbstr,  
   size_t count   
); // C++ only  
template <size_t size>  
size_t _mbstowcs_l(  
   wchar_t (&wcstr)[size],  
   const char *mbstr,  
   size_t count,  
   _locale_t locale  
); // C++ only  

Paramètres

[out] wcstr
L’adresse d’une séquence de caractères larges.

[in] mbstr
L’adresse d’une séquence de null s’est arrêté de caractères multioctets.

[in] count
Le nombre maximal de caractères multioctets à convertir.

[in] locale
Paramètres régionaux à utiliser.

Si mbstowcs convertit correctement la chaîne source, elle retourne le nombre de caractères multioctets converties. Si le wcstr argument est NULL, la fonction retourne la taille requise (en caractères larges) de la chaîne de destination. Si mbstowcs rencontre un caractère multioctet non valide, elle retourne -1. Si la valeur de retour est count, la chaîne de caractères larges n’est pas nul.

System_CAPS_ICON_important.jpg Important

Vérifiez que wcstr et mbstr ne se chevauchent pas, et que count reflète correctement le nombre de caractères multioctets à convertir.

Le mbstowcs fonction convertit un nombre maximal de count caractères multioctets pointée par mbstr en une chaîne de caractères larges correspondants qui sont déterminés par les paramètres régionaux actuels. Il stocke la chaîne de caractères larges obtenue à l’adresse représentée par wcstr . Le résultat est similaire à une série d’appels à mbtowc. Si mbstowcs rencontre le caractère null de sur un octet ('\0') avant ou quand count se produit, il convertit le caractère null pour un caractère null de caractères larges (L '\0') et s’arrête. Par conséquent la chaîne de caractères larges à wcstr est nul uniquement si un caractère null est rencontré pendant la conversion. Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement est indéfini.

Si le wcstr argument est NULL, mbstowcs renvoie le nombre de caractères larges qui résulterait de la conversion, ne notamment pas une marque de fin null. La chaîne source doit être terminée pour la valeur correcte à retourner. Si vous avez besoin de la chaîne de caractères larges résultant soit nul, ajouter un à la valeur retournée.

Si le mbstr argument est NULL, ou si count est > INT_MAX, le Gestionnaire de paramètre non valide est appelé, comme décrit dans Validation de paramètre . Si l’exécution est autorisée à se poursuivre, errno a EINVAL et la fonction retourne -1.

mbstowcsutilise les paramètres régionaux actuels pour tout comportement dépendant des paramètres régionaux ; _mbstowcs_l est identique, sauf qu’elle utilise les paramètres régionaux passé à la place. Pour plus d’informations, consultez Locale.

En C++, ces fonctions ont des surcharges de modèle qui appellent les équivalents plus récents et sécurisés de ces fonctions. Pour plus d'informations, consultez Secure Template Overloads.

RoutineEn-tête requis
mbstowcs<stdlib.h>
_mbstowcs_l<stdlib.h>

Pour plus d'informations sur la compatibilité, voir Compatibilité dans l'introduction.

// crt_mbstowcs.c  
// compile with: /W3  
// illustrates the behavior of the mbstowcs function  
  
#include <stdlib.h>  
#include <stdio.h>  
#include <locale.h>  
  
int main( void )  
{  
    size_t size;  
    int nChar = 2; // number of characters to convert  
    int requiredSize;  
  
    unsigned char    *pmbnull  = NULL;  
    unsigned char    *pmbhello = NULL;  
    char* localeInfo;  
  
    wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters  
    wchar_t *pwc;  
  
    /* Enable the Japanese locale and codepage */  
    localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");  
    printf("Locale information set to %s\n", localeInfo);  
  
    printf( "Convert to multibyte string:\n" );  
  
    requiredSize = wcstombs( NULL, pwchello, 0); // C4996  
    // Note: wcstombs is deprecated; consider using wcstombs_s  
    printf("  Required Size: %d\n", requiredSize);  
  
    /* Add one to leave room for the null terminator. */  
    pmbhello = (unsigned char *)malloc( requiredSize + 1);  
    if (! pmbhello)  
    {  
        printf("Memory allocation failure.\n");  
        return 1;  
    }  
    size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996  
    // Note: wcstombs is deprecated; consider using wcstombs_s  
    if (size == (size_t) (-1))  
    {  
        printf("Couldn't convert string. Code page 932 may"  
                " not be available.\n");  
        return 1;  
    }  
    printf( "  Number of bytes written to multibyte string: %u\n",  
            (unsigned int) size );  
    printf( "  Hex values of the " );  
    printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",  
            pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );  
    printf( "  Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");  
  
    printf( "Convert back to wide-character string:\n" );  
  
    /* Assume we don't know the length of the multibyte string.  
     Get the required size in characters, and allocate enough space. */  
  
    requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996  
    /* Add one to leave room for the NULL terminator */  
    pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));  
    if (! pwc)  
    {  
        printf("Memory allocation failure.\n");  
        return 1;  
    }  
    size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996  
    if (size == (size_t) (-1))  
    {  
       printf("Couldn't convert string--invalid multibyte character.\n");  
    }  
    printf( "  Characters converted: %u\n", (unsigned int)size );  
    printf( "  Hex value of first 2" );  
    printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );  
    free(pwc);  
    free(pmbhello);  
}  

Locale information set to Japanese_Japan.932  
Convert to multibyte string:  
  Required Size: 4  
  Number of bytes written to multibyte string: 4  
  Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1  
  Codepage 932 uses 0x81 to 0x9f as lead bytes.  
  
Convert back to wide-character string:  
  Characters converted: 2  
  Hex value of first 2 wide characters: 0x3042 0x3043  

Non applicable. Pour appeler la fonction C standard, utilisez PInvoke. Pour plus d'informations, consultez Exemples d'appel de plateforme.

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar

Afficher: