wcsrtombs

Článek
03/04/2013

Jeho znázornění řetězec vícebajtových znaků převeďte řetězec znaků.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

[výstup]mbstr
Výsledný převést řetězec vícebajtových znaků adresu umístění.
[v]wcstr
Nepřímo odkazuje na umístění převést řetězec znaků.
[v]count
Počet znaků, které chcete převést.
[v]mbstate
Ukazatel na mbstate_t převodu stavu objektu.

Vrácená hodnota

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

Poznámky

wcsrtombs Funkce převede řetězec znaků široké, od státu zadaný převod obsažené v mbstate, z hodnoty nepřímé označenou v wcstr, na adresu mbstr.Pro každý znak, dokud bude pokračovat v převodu: po zjistil ukončení širokým znakem null, pokud je zjištěna bez odpovídající znak nebo po následující znak by překročil limit obsažené v count.Pokud wcsrtombs narazí znakem null celého znaku (L "\0") před nebo po count dojde, převede ho 8 bit 0 a zastaví.

Tedy řetězec vícebajtových znaků na mbstr je zakončený pouze tehdy, pokud wcsrtombs během převodu zjistí znakem null znaků.Pokud na sekvence odkazuje wcstr a mbstr překrývají, chování wcsrtombs nedefinovaná.wcsrtombsvliv 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 pro následné volání na stejné nebo jiné funkce s možností restartování.Výsledky nedefinované při použití funkce restartování a nonrestartable.Například použít aplikaci wcsrlen namísto 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íl ř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í, je vrácena hodnota -1 a errno je nastavena na EILSEQ.

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

Výjimky

wcsrtombs , Funkce je bezpečné multithread žádná funkce v aktuální podproces volá setlocale v době, kdy je tato funkce spuštění 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" );
    }
}