`wcsrtombs_s`

Článek
10/12/2023

Převede široký řetězec znaků na reprezentaci vícebajtového znakového řetězce. Verze wcsrtombs s vylepšeními zabezpečení, jak je popsáno v funkcích zabezpečení v CRT.

Syntaxe

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

Parametry

pReturnValue
Velikost vbajch

mbstr
Adresa vyrovnávací paměti pro výsledný převedený vícebajtový řetězec znaků.

sizeInBytes
Velikost v bajtech mbstr vyrovnávací paměti.

wcstr
Odkazuje na široký řetězec znaků, který se má převést.

count
Maximální počet bajtů, které mají být uloženy ve mbstr vyrovnávací paměti, nebo _TRUNCATE.

mbstate
Ukazatel na objekt stavu převodu mbstate_t .

Vrácená hodnota

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

Chybový stav	Návratová hodnota a `errno`
`mbstr` je `NULL` a `sizeInBytes`> 0	`EINVAL`
`wcstr` 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`

Pokud dojde k některé z těchto podmínek, je vyvolána 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 wcsrtombs_s převede řetězec širokých znaků odkazovaných na wcstr vícebajtové znaky uložené ve vyrovnávací paměti, na které mbstrodkazuje , pomocí stavu převodu obsaženého v mbstate. Převod bude pokračovat pro každý znak, dokud nebude splněna jedna z těchto podmínek:

Byl zjištěn znak s šířkou null.
Je zjištěn široký znak, který nelze převést.
Počet bajtů uložených ve mbstr vyrovnávací paměti se rovná count.

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 wcsrtombs_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 wcsrtombs_s se zdrojový řetězec úspěšně převede, umístí velikost v bajtech 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ě mbstr , že argument je NULL; poskytuje způsob, jak určit požadovanou velikost vyrovnávací paměti. Pokud mbstr je , count NULLje ignorována.

Pokud wcsrtombs_s narazí na široký znak, nemůže převést na vícebajtový znak, umístí hodnotu -1 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í wcstr na a mbstr překrývají se, chování wcsrtombs_s není definováno. wcsrtombs_s je ovlivněna LC_TYPE kategorií aktuálního národního prostředí.

Důležité

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

Funkce wcsrtombs_s se liší od wcstombs_smožnosti _wcstombs_s_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ísto wcsrlen wcslen, pokud následné volání wcsrtombs_s bylo použito místo wcstombs_s.

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.

Výjimky

Funkce wcsrtombs_s je vícevláknová bezpečná, pokud žádná funkce v aktuálním vlákně volání setlocale při provádění této funkce a mbstate má hodnotu null.

Příklad

// crt_wcsrtombs_s.cpp
//
// 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;
    errno_t         err;
    mbstate_t       mbstate;

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

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Požadavky

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

Viz také

Konverze dat
Národní prostředí
Interpretace vícebajtových sekvencí znaků
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Sdílet prostřednictvím