mbstowcs, _mbstowcs_l

Article
03/04/2013

Convertit une séquence de caractères multioctets à une séquence correspondante à caractères larges.plus les versions sécurisées de ces fonctions sont disponibles ; consultez 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 nulle a terminé les caractères multioctets.
[in] count
le nombre maximal de caractères multioctets à convertir.
[in] locale
Les paramètres régionaux à utiliser.

Valeur de retour

Si mbstowcs convertit correctement la chaîne source, elle retourne le nombre de caractères multioctets convertis.Si l'argument d' wcstr est NULL, la fonction retourne la taille requise (en caractère élargi) de la chaîne de destination.Si mbstowcs rencontre un caractère multioctets valide, elle retourne et 1.si la valeur de retour est count, la chaîne à caractères larges n'est pas se terminant par null.

Note de sécurité
Assurez -vous qu' wcstr et mbstr ne se chevauchent pas, et qu' count reflète correctement le nombre de caractères multioctets pour convertir.

Notes

Le convertit de fonction d' mbstowcs jusqu'à un nombre maximal de caractères multioctets d' count entrées figurant dans mbstr à une chaîne de caractères larges correspondants qui sont déterminés par les paramètres régionaux.Elle enregistre la chaîne à caractères larges obtenu à l'adresse représentée par wcstr*.* le résultat est semblable à une série d'appels à mbtowc.Si mbstowcs rencontre le caractère NULL codé sur un octet (" \ 0 ") ou avant ou lorsque count se produit, il convertit le caractère NULL à un caractère Null à caractères larges (L \ 0 ') et s'arrête.Donc la chaîne à caractères larges à l'adresse wcstr se terminant par null uniquement si un caractère Null est produit pendant la conversion.Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement n'est pas défini.

Si l'argument d' wcstr est NULL, mbstowcs retourne le nombre de caractères larges qui peuvent en résulter de la conversion, sans inclure une marque de fin null.La chaîne source doit être se terminant par null pour que la valeur appropriée soit retournée.Si vous avez besoin de la chaîne à caractères larges obtenu pour être se terminant par null, ajoutez -en une à la valeur retournée.

si l'argument d' mbstr est NULL, ou si count est > INT_MAX, 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, l'errno est défini à EINVAL et retourne de fonction -1.

mbstowcs utilise les paramètres régionaux définis pour tout comportement dépendant des paramètres régionaux ; _mbstowcs_lest identique mais il utilise les paramètres régionaux passés à la place.Pour plus d'informations, consultez Paramètres régionaux.

En C++, ces fonctions ont des surcharges de modèle qui appellent des homologues plus récentes et sécurisées de ces fonctions.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Configuration requise

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

Pour des informations de compatibilité supplémentaires, consultez compatibilité dans l'introduction.

Exemple

// 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);
}