mbsrtowcs

Převede řetězec vícebajtového znaku v aktuálním národním prostředí na odpovídající řetězec širokého znaku s možností restartování uprostřed vícebajtového znaku. K dispozici je bezpečnější verze této funkce; viz .mbsrtowcs_s

Syntaxe

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

Parametry

wcstr
Adresa pro uložení výsledného převedeného řetězce širokého znaku

mbstr
Nepřímý ukazatel na umístění vícebajtového znakového řetězce, který chcete převést.

count
Maximální počet znaků (nikoli bajtů) pro převod a uložení v wcstr.

mbstate
Ukazatel na objekt stavu převodu mbstate_t . Pokud je tato hodnota ukazatel null, použije se objekt stavu statického interního převodu. Protože interní mbstate_t objekt není bezpečný pro přístup z více vláken, doporučujeme vždy předat vlastní mbstate parametr.

Vrácená hodnota

Vrátí počet znaků, které byly úspěšně převedeny, a neobsahuje ukončující znak null, pokud existuje. Vrátí (size_t)(-1), pokud došlo k chybě a nastaví errno hodnotu EILSEQ.

Poznámky

Funkce mbsrtowcs převede řetězec vícebajtových znaků, na který mbstrnepřímo odkazuje , na široké znaky uložené ve vyrovnávací paměti, na kterou wcstrodkazuje , pomocí stavu převodu obsaženého v mbstate. Převod pokračuje u každého znaku, dokud nebude zjištěn ukončující vícebajtový znak null, vícebajtovou sekvenci, která neodpovídá platnému znaku v aktuálním národním prostředí, nebo dokud count nebudou převedeny znaky. Pokud mbsrtowcs narazí na vícebajtový znak null ('\0') buď před nebo kdy count nastane, převede ho na 16bitový ukončující znak null a zastaví.

Proto je řetězec širokého znaku s wcstr hodnotou null ukončen pouze v případě, že mbsrtowcs během převodu narazí na vícebajtový znak null. Pokud se sekvence ukazující mbstr na a wcstr překrývají se, chování mbsrtowcs není definováno. mbsrtowcs je ovlivněna LC_TYPE kategorií aktuálního národního prostředí.

Funkce mbsrtowcs se liší od mbstowcsmožnosti _mbstowcs_l restartování. Stav převodu se uloží mbstate pro následná volání stejných nebo jiných restartovatelných funkcí. Výsledky nejsou definovány při kombinování použití restartovatelných a nerestartovatelných funkcí. Například aplikace by měla místo mbsrlen mbslen, pokud se použije následné volání mbsrtowcs místo mbstowcs.

Pokud wcstr není ukazatel null, je objekt ukazatele, na který mbstr odkazuje, přiřazen ukazatel null, pokud převod přestal, protože byl dosažen ukončující znak null. V opačném případě se adresa přiřadí za poslední vícebajtový znak převedený, pokud existuje. Umožňuje následné volání funkce restartovat převod tam, kde se toto volání zastavilo.

wcstr Pokud je argument ukazatelem null, count argument se ignoruje a mbsrtowcs vrátí požadovanou velikost širokých znaků pro cílový řetězec. Pokud mbstate je ukazatel null, funkce používá objekt stavu statického mbstate_t interního převodu bez vláken bezpečný. Pokud sekvence mbstr znaků nemá odpovídající vícebajtovou reprezentaci znaků, vrátí se hodnota -1 a errno nastaví se na EILSEQhodnotu .

Pokud mbstr je ukazatel null, je vyvolána neplatná obslužná rutina parametru, jak je popsáno v ověření parametru. Pokud je spuštění povoleno pokračovat, tato funkce nastaví errno EINVAL hodnotu -1 a vrátí hodnotu -1.

V jazyce C++ má tato funkce přetížení šablony, které vyvolá novější zabezpečený protějšk této funkce. 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.

Výjimky

Funkce mbsrtowcs je vícevláknová bezpečná, pokud žádná funkce v aktuálním vlákně volá setlocale , pokud se tato funkce spouští a mbstate argument není ukazatelem null.

Požadavky

Rutina	Požadovaný hlavičkový soubor
mbsrtowcs	<wchar.h>

Viz také

Konverze dat
Národní prostředí
Interpretace vícebajtových sekvencí znaků
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit