mbstowcs, _mbstowcs_l

Článek
06/09/2015

Posloupnost vícebajtové znaky převede na odpovídající sekvenci znaků široký.Bezpečnější verze těchto funkcí jsou k dispozici; viz 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

[out] wcstr
Adresa posloupnost znaků na šířku.
[v] mbstr
Adresa sekvence null ukončena vícebajtové znaky.
[in] count
Maximální počet vícebajtové znaky, které chcete převést.
[in] locale
Použité národní prostředí.

Vrácená hodnota

Pokud mbstowcs úspěšně převádí zdrojový řetězec, vrátí převedené vícebajtové znaky.Pokud wcstr argument je NULL, vrátí funkce požadované velikosti (v široké znaky) cílový řetězec.Pokud mbstowcs nalezne neplatný vícebajtové znakové vrátí -1.Pokud je vrácená hodnota count, řetězec širokého znaku není zakončený hodnotou null.

Poznámka k zabezpečení
Zajistit, aby wcstr a mbstr se nepřekrývají a že count správně odpovídá počtu vícebajtové znaky, které chcete převést.

Poznámky

mbstowcs Funkce převede maximální počet count vícebajtových znaků ukazující na 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 širokého znaku na adrese reprezentované wcstr*.* Výsledkem je posloupnost volání podobné mbtowc.Pokud mbstowcs narazí jednobajtové znak null ('\0') před nebo po count dojde, převede znak null znak null širokého znaku (L '\0') a zastaví.Tedy řetězce širokého znaku na wcstr je zakončený pouze v případě, že během převodu došlo k znak null.Pokud je sekvence odkazuje wcstr a mbstr překrytí, chování není definováno.

Pokud wcstr argument je NULL, mbstowcs vrací počet široké znaky, které by mohly být výsledkem převodu, ne včetně null zakončení.Zdrojový řetězec musí být zakončený správné hodnoty mají být vráceny.Pokud potřebujete výsledný řetězec širokého znaku být zakončený hodnotou null, přidáte vrácené hodnoty.

Pokud mbstr argument je NULL, nebo -li count je >INT_MAX, je vyvolán neplatný parametr obslužné rutiny, jak je popsáno v Ověření parametru .Pokud je povoleno pokračovat v provádění, kód chyby je nastavena na EINVAL a vrátí -1.

mbstowcspoužívá aktuální národní prostředí pro všechny závislé chování; _mbstowcs_l je totožný s tím rozdílem, že používá místo něho předán národní prostředí.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í zabezpečení šablony.

Požadavky

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

Další informace o kompatibilitě naleznete v úvodu 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);
}