wcsrtombs

Artykuł
06/09/2015

Przekonwertować ciąg znaków szerokości na jego reprezentację ciąg znaków wielobajtowych.Bezpieczniejszą wersją tej funkcji jest dostępna; see wcsrtombs_s.

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

[poza] mbstr
Wynikowy przekonwertować ciąg znaków wielobajtowych adres lokalizacji.
[in] wcstr
Pośrednio wskazuje lokalizację znak dwubajtowy ciąg do konwersji.
[in] count
Liczba znaków, które mają być konwertowane.
[in] mbstate
Wskaźnik do mbstate_t obiekt stanu konwersji.

Wartość zwracana

Zwraca liczbę bajtów pomyślnie przekonwertowane, nie tym null kończące bajtem null (jeśli istnieje), w przeciwnym razie -1, jeśli wystąpił błąd.

Uwagi

wcsrtombs Funkcja konwertuje ciąg znaków szeroki, począwszy od stanu określonej konwersji zawartych w mbstate, od wartości pośrednie wskazał w wcstr, pod adresem mbstr.Konwersja będzie nadal dla każdego znaku do: po napotkał wartość null kończące znak dwubajtowy po napotkaniu innych niż odpowiedni znak lub podczas następnego znaku mogłaby przekroczyć limit zawartych w count.Jeśli wcsrtombs napotka znakiem znak null (L '\0') przed lub po count występuje, konwertuje ją na 8-bitowe 0 i zatrzymuje się.

Tak więc ciąg znaków wielobajtowych w mbstr jest zakończony znakiem null tylko wtedy, gdy wcsrtombs napotka znak dwubajtowy znak null podczas konwersji.Jeśli sekwencje wskazywanego przez wcstr i mbstr nachodzą na siebie, zachowanie wcsrtombs jest niezdefiniowane.wcsrtombsdotyczy kategorii LC_TYPE bieżące ustawienia regionalne.

wcsrtombs Funkcja różni się od wcstombs, _wcstombs_l przez jego restartability.Stan konwersji jest przechowywany w mbstate dla kolejnych zaproszeń do tej samej lub innych funkcji ponownego uruchamiania.Wyniki są nieokreślone, podczas ponownego uruchamiania i nonrestartable funkcji mieszania. Na przykład, aplikacja będzie używać wcsrlen zamiast wcsnlen, jeśli kolejne wywołanie wcsrtombs były używane zamiast wcstombs.

Jeśli mbstr argument jest NULL, wcsrtombs zwraca wymagany rozmiar w bajtach ciąg docelowego.Jeśli mbstate ma wartość null, wewnętrznego mbstate_t stan konwersji jest używany.Jeżeli sekwencja znaków wchar nie ma odpowiedniej wielobajtowe reprezentacji znaków, zwracane jest -1 i errno jest ustawiona na EILSEQ.

W języku C++ funkcja ta ma przeciążenie szablon, który wywołuje nowsze, bezpieczne odpowiednika tej funkcji.Aby uzyskać więcej informacji, zobacz Przeciążenia bezpiecznych szablonów.

Wyjątki

wcsrtombs Funkcja jest wielowątkowym bezpieczna, tak długo, jak nie funkcja w bieżącym wątku wywołuje setlocale podczas wykonywania tej funkcji i mbstate nie ma wartości null.

Przykład

// 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" );
    }
}