Sdílet prostřednictvím

mbstowcs_s, _mbstowcs_s_l

  • Článek

Převede posloupnost vícebajtových znaků na odpovídající sekvenci širokých znaků. mbstowcsVerze , _mbstowcs_l s vylepšeními zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Syntaxe

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parametry

pReturnValue
Počet převedených znaků.

wcstr
Adresa vyrovnávací paměti pro výsledný převedený řetězec širokého znaku.

sizeInWords
Velikost wcstr vyrovnávací paměti ve slovech.

mbstr
Adresa sekvence s vícebajtovým ukončením null.

count
Maximální počet širokých znaků, které se mají uložit do wcstr vyrovnávací paměti, včetně ukončující hodnoty null nebo _TRUNCATE.

locale
Národní prostředí, které se má použít

Vrácená hodnota

Nula v případě úspěchu, kód chyby při selhání.

Chybový stav Návratová hodnota a errno
wcstr je NULL a sizeInWords> 0 EINVAL
mbstr je NULL EINVAL
Cílová vyrovnávací paměť je příliš malá, aby obsahovala převedený řetězec (pokud count není _TRUNCATE; viz poznámky níže) ERANGE
wcstr není NULL a sizeInWords == 0 EINVAL

Pokud dojde k některé z těchto podmínek, vyvolá se neplatná výjimka parametru, jak je popsáno v ověření parametru. Pokud je spuštění povoleno pokračovat, vrátí funkce kód chyby a nastaví errno , jak je uvedeno v tabulce.

Poznámky

Funkce mbstowcs_s převede řetězec vícebajtových znaků odkazovaných na mbstr široké znaky uložené ve vyrovnávací paměti odkazované na wcstr. Převod bude pokračovat pro každý znak, dokud nebude splněna jedna z těchto podmínek:

  • Byl zjištěn vícebajtový znak null.

  • Byl zjištěn neplatný znak s vícebajty.

  • Počet širokých znaků uložených wcstr ve vyrovnávací paměti se countrovná .

Cílový řetězec je vždy ukončen s hodnotou null (i když dojde k chybě).

Pokud count je speciální hodnota _TRUNCATE, pak mbstowcs_s převede tolik řetězce, jak se vejde do cílové vyrovnávací paměti, zatímco stále ponechá prostor pro ukončení null.

Pokud mbstowcs_s se zdrojový řetězec úspěšně převede, umístí velikost široké znaky převedeného řetězce, včetně ukončovací funkce null, do *pReturnValue (zadané pReturnValue není NULL). Velikost se vypočítá i v případě wcstr , že argument je NULL, a poskytuje způsob, jak určit požadovanou velikost vyrovnávací paměti. Pokud wcstr je hodnota NULL, count bude ignorována a sizeInWords musí být 0.

Pokud mbstowcs_s narazí na neplatný vícebajtový znak, umístí hodnotu 0 do *pReturnValue, nastaví cílovou vyrovnávací paměť na prázdný řetězec, nastaví errno hodnotu EILSEQa vrátí EILSEQ.

Pokud se sekvence ukazující mbstr na a wcstr překrývají se, chování mbstowcs_s není definováno.

Důležité

Zajistěte, aby wcstr se nepřekrývaly mbstr a aby count správně odrážely počet vícebajtových znaků, které se mají převést.

mbstowcs_s používá aktuální národní prostředí pro jakékoli chování závislé na národním prostředí; _mbstowcs_s_l je shodný s tím rozdílem, že místo toho používá národní prostředí předané. Další informace naleznete v tématu Národní prostředí.

V jazyce C++ je použití těchto funkcí zjednodušeno přetíženími šablon; přetížení mohou automaticky odvodit délku vyrovnávací paměti (eliminuje potřebu zadat argument velikosti) a mohou automaticky nahradit starší, nezabezpečené funkce jejich novějšími zabezpečenými protějšky. 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.

Požadavky

Rutina Požadovaný hlavičkový soubor
mbstowcs_s <stdlib.h>
_mbstowcs_s_l <stdlib.h>

Další informace o kompatibilitě najdete v tématu Kompatibilita.

Viz také

Konverze dat
Národní prostředí
MultiByteToWideChar
Interpretace vícebajtových sekvencí znaků
_mbclen, , mblen_mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l