Sdílet prostřednictvím

wcstombs_s, _wcstombs_s_l

  • Článek

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

Syntaxe

errno_t wcstombs_s(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count
);

errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char *mbstr,
   size_t sizeInBytes,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);

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

template <size_t size>
errno_t _wcstombs_s_l(
   size_t *pReturnValue,
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // 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é se mají uložit do mbstr vyrovnávací paměti, včetně ukončujícího znaku 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
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, 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 wcstombs_s převede řetězec širokých znaků odkazovaných na wcstr vícebajtové znaky uložené ve vyrovnávací paměti odkazované na mbstr. 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 wcstombs_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 je řetězec zkrácen, návratová hodnota je STRUNCATEa převod se považuje za úspěšný.

Pokud wcstombs_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 wcstombs_s narazí na široký znak, nemůže převést na vícebajtový znak, umístí hodnotu 0 do *ReturnValue, 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í wcstombs_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 širokých znaků, které chcete převést.

wcstombs_s používá aktuální národní prostředí pro jakékoli chování závislé na národním prostředí; _wcstombs_s_l je shodný s tím rozdílem wcstombs , ž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
wcstombs_s <stdlib.h>

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

Příklad

Tento program znázorňuje chování wcstombs_s funkce.

// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t i;
    char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    const wchar_t*pWCBuffer = L"Hello, world.";

    printf( "Convert wide-character string:\n" );

    // Conversion
    wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
               pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer

    // Output
    printf("   Characters converted: %u\n", i);
    printf("    Multibyte character: %s\n\n", pMBBuffer );

    // Free multibyte character buffer
    if (pMBBuffer)
    {
        free(pMBBuffer);
    }
    
    return 0;
}

Convert wide-character string:
   Characters converted: 14
    Multibyte character: Hello, world.

Viz také

Konverze dat
Národní prostředí
_mbclen, , mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb_s, _wctomb_s_l
WideCharToMultiByte