mbstowcs _mbstowcs_l

Článek
03/04/2013

Převede odpovídající posloupnost znaků celou posloupnost vícebajtových znaků.Bezpečnější verze tyto funkce jsou k dispozici; see 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

Parametry

[výstup]wcstr
Adresa posloupnost znaků široký.
[v]mbstr
Adresa sekvence null ukončena vícebajtových znaků.
[v]count
Maximální počet převodu vícebajtových znaků.
[v]locale
Národní prostředí použít.

Vrácená hodnota

Pokud mbstowcs úspěšně převede řetězec zdroje vrátí převedené vícebajtových znaků.Pokud wcstr argument je NULL, vrátí funkce požadované velikosti (v široké znaků), řetězec cílové.Pokud mbstowcs nalezne neplatný vícebajtové znakové vrátí hodnotu –1.Pokud je vrácená hodnota je count, není wide znakový řetězec zakončený hodnotou null.

Poznámka k zabezpečení
Zajistit, aby wcstr a mbstr nepřekrývají a že count správně odráží počet převodu vícebajtových znaků.

Poznámky

mbstowcs Funkce převede maximální počet count vícebajtových znaků odkazuje mbstr na řetězec odpovídající široký znaky, které jsou určeny pro aktuální národní prostředí.Uloží výsledný řetězec znaků wide na adrese reprezentované wcstr*.* Výsledek je podobný série volání mbtowc.Pokud mbstowcs narazí null jednobajtových znaků (\0) před nebo po count dojde, převede znak null znakem null celého znaku (L "\0") a zastaví.Tedy wide znakový řetězec na wcstr je zakončený pouze tehdy, pokud je během převodu došlo k znakem null.Pokud na sekvence odkazuje wcstr a mbstr překrytí, chování není definován.

Pokud wcstr argument je NULL, mbstowcs vrací počet široké znaky, které by vyplývaly z převodu, včetně není null zakončení.Zdrojový řetězec musí být zakončený vrátit na správnou hodnotu.Pokud potřebujete výsledný řetězec znaků je zakončený hodnotou null, přidáte vrácené hodnoty.

If the mbstr argument is NULL, or if count is > INT_MAX, vyvolat neplatný parametr popisovače, jak je popsáno v Ověření parametrů .Pokud je povoleno spuštění pokračovat, kód chyby je nastavena na EINVAL a vrátí -1.

mbstowcspoužívá aktuální národní prostředí pro všechny národní prostředí závislé na chování; _mbstowcs_l je identické používá místo předaný národní prostředí.Další informace naleznete v tématu Národní prostředí.

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

Požadavky

Rutina	Požadované záhlaví
mbstowcs	<stdlib.h>
_mbstowcs_l	<stdlib.h>

Další informace o kompatibilitě, viz Compatibility v úvodu.

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