mbstowcs, _mbstowcs_l

Převede posloupnost vícebajtových znaků na odpovídající sekvenci širokých znaků. K dispozici jsou bezpečnější verze těchto funkcí; viz mbstowcs_s, _mbstowcs_s_l.

Syntaxe

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

Parametry

wcstr
Adresa posloupnosti širokých znaků.

mbstr
Adresa sekvence s vícebajtovým ukončením null.

count
Maximální počet vícebajtových znaků, které chcete převést.

locale
Národní prostředí, které se má použít

Vrácená hodnota

Pokud mbstowcs se zdrojový řetězec úspěšně převede, vrátí počet převedených vícebajtových znaků. wcstr Pokud je NULLargumentem, vrátí funkce požadovanou velikost (v širokých znaznachech) cílového řetězce. Pokud mbstowcs dojde k neplatnému vícebajtového znaku, vrátí hodnotu -1. Pokud je countvrácená hodnota , řetězec s širokým znakem není ukončen s hodnotou null.

Poznámky

Funkce mbstowcs převede až na maximální počet vícebajtových count znaků odkazovaných mbstr na řetězec odpovídajících širokých znaků určených aktuálním národním prostředím. Uloží výsledný řetězec širokého znaku na adrese reprezentované wcstr. Výsledek je podobný řadě volání mbtowc. Pokud mbstowcs dojde k výskytu znaku null s jedním bajtem (\0) před nebo v count případě výskytu, převede znak null na znak null s širokým znakem null (L'\0') a zastaví se. Řetězec s širokým znakem v wcstr hodnotě null je tedy ukončen pouze v případě, že je při převodu zjištěn znak null. Pokud se sekvence ukazující wcstr na a mbstr překrývají se, chování není definováno.

wcstr Pokud argument je NULL, mbstowcs vrátí počet širokých znaků, které by výsledkem převodu, nikoli zahrnutí ukončovací funkce null. Zdrojový řetězec musí být ukončen s hodnotou null, aby se vrátila správná hodnota. Pokud potřebujete výsledný řetězec širokého znaku, který má být ukončen s hodnotou null, přidejte ho k vrácené hodnotě.

mbstr Pokud je argument , nebo pokud count je NULLINT_MAX>, je vyvolána neplatná obslužná rutina parametru, jak je popsáno v ověření parametru. Pokud je spuštění povoleno pokračovat, errno je nastaveno na EINVAL hodnotu a funkce vrátí hodnotu -1.

mbstowcs používá aktuální národní prostředí pro jakékoli chování závislé na národním prostředí; _mbstowcs_l je shodný s tím rozdílem, že místo toho používá národní prostředí předané. Další informace naleznete v tématu Národní prostředí.

V jazyce C++ mají tyto funkce přetížení šablon, které vyvolávají novější zabezpečené protějšky těchto funkcí. Další informace naleznete v tématu Přetížení šablon zabezpečení.

Ve výchozím nastavení je globální stav této funkce vymezen na aplikaci. Chcete-li toto chování změnit, přečtěte si téma Globální stav v CRT.

Požadavky

Další informace o kompatibilitě najdete v tématu Kompatibilita.

Příklad

// 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

Viz také

Konverze dat
Národní prostředí
Interpretace vícebajtových sekvencí znaků
_mbclen, , mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar