`wcsrtombs`

Článek
10/12/2023

Převede široký řetězec znaků na reprezentaci vícebajtového znakového řetězce. K dispozici je bezpečnější verze této funkce; viz .wcsrtombs_s

Syntaxe

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

mbstr
Výsledné umístění adresy vícebajtového řetězce vícebajtového znaku.

wcstr
Nepřímo odkazuje na umístění širokého znakového řetězce, který se má převést.

count
Počet znaků, které se mají převést.

mbstate
Ukazatel na objekt stavu převodu mbstate_t .

Vrácená hodnota

Vrátí počet bajtů, které byly úspěšně převedeny, a neobsahuje nulový ukončovací bajt null (pokud existuje), jinak hodnota -1, pokud došlo k chybě.

Poznámky

Funkce wcsrtombs převede řetězec širokých znaků, počínaje zadaným stavem převodu obsaženým mbstatev hodnotách nepřímých odkazovaných na wcstr, na adresu mbstr. Převod bude pokračovat pro každý znak až do: po ukončení celého znaku null, pokud je zjištěn jiný než odpovídající znak nebo pokud by další znak překročil limit obsažený v count. Pokud wcsrtombs se setkáte se znakem null širokého znaku (L'\0'), a to buď před nebo kdy count nastane, převede ho na 8bitovou 0 a zastaví.

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

Funkce wcsrtombs se liší od wcstombsmožnosti _wcstombs_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 wcsnlen, pokud následné volání wcsrtombs bylo použito místo wcstombs.

mbstr Pokud argument je NULL, wcsrtombs vrátí požadovanou velikost v bajtech cílového řetězce. Pokud mbstate je hodnota null, použije se stav interního mbstate_t převodu. Pokud sekvence wchar znaků nemá odpovídající vícebajtovou reprezentaci znaků, vrátí se hodnota -1 a errno nastaví se na EILSEQhodnotu .

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 wcsrtombs je vícevláknová bezpečná, pokud v aktuálním vlákně nevolá setlocale žádná funkce, zatímco se tato funkce spouští 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" );
    }
}

The string was successfuly converted.

Požadavky

Rutina	Požadovaný hlavičkový soubor
`wcsrtombs`	<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