wcsrtombs

Článek
06/09/2015

Převeďte řetězec širokého znaku na jeho znázornění vícebajtové znakové řetězce.Bezpečnější verze této funkce je k dispozici. see wcsrtombs_s.

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parametry

[out] mbstr
Výsledné převedené vícebajtový řetězec umístění adresy.
[in] wcstr
Nepřímo odkazuje na umístění, které chcete převést řetězce širokého znaku.
[in] count
Počet znaků, které chcete převést.
[in] mbstate
Ukazatel mbstate_t převodu stavu objektu.

Vrácená hodnota

Vrátí počet bajtů úspěšně převeden, ne včetně null ukončení bajtu null (pokud existuje), jinak -1, pokud dojde k chybě.

Poznámky

wcsrtombs Funkce převede řetězec znaků široký, počínaje Zadaný převod stavu obsažené v mbstate, z hodnoty nepřímé nastavena v wcstr, na adresu mbstr.Převod bude pro každý znak do: po ukončení široký znak null je zjištěna vyskytne bez odpovídající znak nebo další znak by překročil omezení obsažená v count.Pokud wcsrtombs narazí širokého znaku prázdný znak (L '\0') před nebo po count dojde, převede ho 8-bit 0 a zastaví.

Tedy vícebajtové znakové řetězce na mbstr je zakončený pouze tehdy, pokud wcsrtombs během převodu zjistí širokého znaku prázdný znak.Pokud je sekvence odkazuje wcstr a mbstr překrývají, chování wcsrtombs není definována.wcsrtombsje ovlivněn LC_TYPE kategorie aktuální národní prostředí.

wcsrtombs Funkce se liší od wcstombs, _wcstombs_l podle jeho restartability.Stav převodu je uložen v mbstate na stejné nebo jiné funkce restartování následné volání.Při použití funkce restartování a nonrestartable nedefinované výsledky. Například by aplikace používat wcsrlen spíše než wcsnlen, pokud následné volání wcsrtombs byly použity namísto wcstombs.

Pokud mbstr argument je NULL, wcsrtombs vrátí požadovaná velikost v bajtech cílový řetězec.Pokud mbstate má hodnotu null, vnitřní mbstate_t slouží k převodu stavu.Pokud je sekvence znaků wchar nemá odpovídající vícebajtové znakové vyjádření -1 je vrácena a errno je nastavena na EILSEQ.

Tuto funkci v jazyce C++ má přetížení šablonu, která vyvolá novější, zabezpečený protějšek této funkce.Další informace naleznete v tématu Přetížení zabezpečení šablony.

Výjimky

wcsrtombs Funkce je bezpečné s více vlákny, dokud není žádná funkce v aktuálním vlákně, volání setlocale v době, kdy je spuštění této funkce a mbstate není null.

Příklad

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfuly converted.\n" );
    }
}